Square Payments (Independent Publisher) (Preview)

Square helps millions of sellers run their business - from secure credit card processing to point of sale solutions. This connector contains actions for the following endpoints: Payments, Terminal, Orders, Subscriptions, Invoices, Catalog, Inventory and Customers.

This connector is available in the following products and regions:

Service	Class	Regions
Logic Apps	Standard	All Logic Apps regions except the following:      -   Azure Government regions      -   Azure China regions      -   US Department of Defense (DoD)
Power Automate	Premium	All Power Automate regions except the following:      -   US Government (GCC)      -   US Government (GCC High)      -   China Cloud operated by 21Vianet      -   US Department of Defense (DoD)
Power Apps	Premium	All Power Apps regions except the following:      -   US Government (GCC)      -   US Government (GCC High)      -   China Cloud operated by 21Vianet      -   US Department of Defense (DoD)

Contact
Name	Troy Taylor
URL	https://www.hitachisolutions.com
Email	ttaylor@hitachisolutions.com

Connector Metadata
Publisher	Troy Taylor
Website	https://squareup.com/
Privacy policy	https://squareup.com/us/en/legal/general/privacy
Categories	Commerce;Sales and CRM

Throttling Limits

Name	Calls	Renewal Period
API calls per connection	100	60 seconds

Actions

Accept dispute	Accepts the loss on a dispute. Square returns the disputed amount to the cardholder and updates the dispute state to ACCEPTED. Square debits the disputed amount from the seller’s Square account. If the Square account does not have sufficient funds, Square debits the associated bank account.
Add group to customer	Adds a group membership to a customer. The customer is identified by the customer_id value and the customer group is identified by the group_id value.
Batch change inventory	Applies adjustments and counts to the provided item quantities. On success: returns the current calculated counts for all objects referenced in the request.
Batch delete catalog objects	Deletes a set of CatalogItems based on the provided list of target IDs and returns a set of successfully deleted IDs in the response.
Batch retrieve catalog objects	Returns a set of objects based on the provided ID. Each CatalogItem returned in the set includes all of its child information including: all of its CatalogItemVariation objects, references to its CatalogModifierList objects, and the ids of any CatalogTax objects that apply to it.
Batch retrieve inventory changes	Returns historical physical counts and adjustments based on the provided filter criteria.
Batch retrieve inventory counts	Returns current counts for the provided CatalogObjects at the requested Locations.
Batch retrieve orders	Retrieves a set of orders by their IDs. If a given order ID does not exist, the ID is ignored instead of generating an error.
Batch upsert catalog objects	Creates or updates up to 10,000 target objects based on the provided list of objects. The target objects are grouped into batches and each batch is inserted/updated in an all-or-nothing manner. If an object within a batch is malformed in some way, or violates a database constraint, the entire batch containing that item will be disregarded. However, other batches in the same request may still succeed. Each batch may contain up to 1,000 objects, and batches will be processed in order as long as the total object count for the request (items, variations, modifier lists, discounts, and taxes) is no more than 10,000.
Calculate order (Beta)	Enables applications to preview order pricing without creating an order.
Cancel invoice	Cancels an invoice. The seller cannot collect payments for the canceled invoice.
Cancel payment	Cancels (voids) a payment. You can use this endpoint to cancel a payment with the APPROVED status.
Cancel payment by idempotency key	Cancels (voids) a payment identified by the idempotency key that is specified in the request. Use this method when the status of a CreatePayment request is unknown (for example, after you send a CreatePayment request, a network error occurs and you do not get a response). In this case, you can direct Square to cancel the payment using this endpoint. In the request, you provide the same idempotency key that you provided in your CreatePayment request that you want to cancel. After canceling the payment, you can submit your CreatePayment request again. Note that if no payment with the specified idempotency key is found, no action is taken and the endpoint returns successfully.
Cancel subscription	Sets the canceled_date field to the end of the active billing period. After this date, the status changes from ACTIVE to CANCELED.
Cancel terminal checkout	Cancels a Terminal checkout request if the status of the request permits it.
Cancel terminal refund	Cancels an Interac Terminal refund request by refund request ID if the status of the request permits it.
Catalog info	Retrieves information about the Square Catalog API, such as batch size limits that can be used by the BatchUpsertCatalogObjects endpoint.
Clone order (Beta)	Creates a new order, in the DRAFT state, by duplicating an existing order. The newly created order has only the core fields (such as line items, taxes, and discounts) copied from the original order.
Complete payment	Completes (captures) a payment. By default, payments are set to complete immediately after they are created.
Create card	Adds a card on file to an existing merchant.
Create customer	Creates a new customer for a business.
Create customer group	Creates a new customer group for a business.
Create dispute evidence text	Uploads text to use as evidence for a dispute challenge.
Create invoice	Creates a draft invoice for an order created using the Orders API. A draft invoice remains in your account and no action is taken. You must publish the invoice before Square can process it (send it to the customer's email address or charge the customer’s card on file).
Create order	Creates a new order that can include information about products for purchase and settings to apply to the purchase.
Create payment	Creates a payment using the provided source. You can use this endpoint to charge a card (credit/debit card or Square gift card) or record a payment that the seller received outside of Square (cash payment from a buyer or a payment that an external entity processed on behalf of the seller).
Create subscription	Creates a subscription for a customer to a subscription plan. If you provide a card on file in the request, Square charges the card for the subscription. Otherwise, Square bills an invoice to the customer's email address. The subscription starts immediately, unless the request includes the optional start_date. Each individual subscription is associated with a particular location.
Create terminal checkout	Creates a Terminal checkout request and sends it to the specified device to take a payment for the requested amount.
Create terminal refund	Creates a request to refund an Interac payment completed on a Square Terminal.
Delete catalog object	Deletes a single CatalogObject based on the provided ID and returns the set of successfully deleted IDs in the response. Deletion is a cascading event such that all children of the targeted object are also deleted. For example, deleting a CatalogItem will also delete all of its CatalogItemVariation children.
Delete customer	Deletes a customer profile from a business. This operation also unlinks any associated cards on file.
Delete customer group	Deletes a customer group as identified by the group_id value.
Delete dispute evidence	Removes specified evidence from a dispute.
Delete invoice	Deletes the specified invoice. When an invoice is deleted, the associated order status changes to CANCELED. You can only delete a draft invoice (you cannot delete a published invoice, including one that is scheduled for processing).
Disable card	Disables the card, preventing any further updates or charges. Disabling an already disabled card is allowed but has no effect.
Get invoice	Retrieves an invoice by invoice ID.
Get payment	Retrieves details for a specific payment.
Get payment refund	Retrieves a specific refund using the refund_id.
Get terminal checkout	Retrieves a Terminal checkout request by checkout_id.
Get terminal refund	Retrieves an Interac Terminal refund object by ID.
List cards	Retrieves a list of cards owned by the account making the request.
List catalog	Returns a list of CatalogObjects that includes all objects of a set of desired types (for example, all CatalogItem and CatalogTax objects) in the catalog. ListCatalog does not return deleted catalog items.
List customer groups	Retrieves the list of customer groups of a business.
List customer segments	Retrieves the list of customer segments of a business.
List customers	Lists customer profiles associated with a Square account. Under normal operating conditions, newly created or updated customer profiles become available for the listing operation in well under 30 seconds. Occasionally, propagation of the new or updated profiles can take closer to one minute or longer, especially during network incidents and outages.
List dispute evidence	Returns a list of evidence associated with a dispute.
List disputes	Returns a list of disputes associated with a particular account.
List invoices	Returns a list of invoices for a given location.
List payment refunds	Retrieves a list of refunds for the account making the request. Results are eventually consistent, and new refunds or changes to refunds might take several seconds to appear.
List payments	Retrieves a list of payments taken by the account making the request. Results are eventually consistent, and new payments or changes to payments might take several seconds to appear.
List subscription events	Lists all events for a specific subscription.
Pay order (Beta)	Pay for an order using one or more approved payments or settle an order with a total of 0. The total of the payment_ids listed in the request must be equal to the order total. Orders with a total amount of 0 can be marked as paid by specifying an empty array of payment_ids in the request.
Publish invoice	Publishes the specified draft invoice. After an invoice is published, Square follows up based on the invoice configuration. For example, Square sends the invoice to the customer's email address, charges the customer's card on file, or does nothing. Square also makes the invoice available on a Square-hosted invoice page.
Refund payment	Refunds a payment. You can refund the entire payment amount or a portion of it. You can use this endpoint to refund a card payment or record a refund of a cash or external payment.
Register domain for Apple Pay	Activates a domain for use with Apple Pay on the Web and Square. A validation is performed on this domain by Apple to ensure that it is properly set up as an Apple Pay enabled domain.
Remove group from customer	Removes a group membership from a customer. The customer is identified by the customer_id value and the customer group is identified by the group_id value.
Resume subscription	Resumes a deactivated subscription.
Retrieve card	Retrieves details for a specific Card.
Retrieve catalog object	Returns a single CatalogItem as a CatalogObject based on the provided ID. The returned object includes all of the relevant CatalogItem information including: CatalogItemVariation children, references to its CatalogModifierList objects, and the ids of any CatalogTax objects that apply to it.
Retrieve customer	Returns details for a single customer.
Retrieve customer group	Retrieves a specific customer group.
Retrieve customer segment	Retrieves a specific customer segment.
Retrieve dispute	Returns details about a specific dispute.
Retrieve dispute evidence	Returns the evidence metadata specified by the evidence ID in the request URL path. You must maintain a copy of the evidence you upload if you want to reference it later. You cannot download the evidence after you upload it.
Retrieve inventory adjustment	Returns the InventoryAdjustment object with the provided adjustment_id.
Retrieve inventory count	Retrieves the current calculated stock count for a given CatalogObject at a given set of Locations.
Retrieve inventory physical count	Returns the InventoryPhysicalCount object with the provided physical_count_id.
Retrieve inventory transfer (Beta)	Returns the InventoryTransfer object with the provided transfer_id.
Retrieve order	Retrieves an Order by ID.
Retrieve subscription	Retrieves a subscription.
Search catalog objects	Searches for CatalogObject of any type by matching supported search attribute values, excluding custom attribute values on items or item variations, against one or more of the specified query filters.
Search customers	Searches the customer profiles associated with a Square account using a supported query filter. Calling SearchCustomers without any explicit query filter returns all customer profiles ordered alphabetically based on given_name and family_name.
Search invoices	Searches for invoices from a location specified in the filter.
Search orders	Search all orders for one or more locations. Orders include all sales, returns, and exchanges regardless of how or when they entered the Square ecosystem (such as Point of Sale, Invoices, and Connect APIs).
Search subscriptions	Searches for subscriptions. Results are ordered chronologically by subscription creation date. If the request specifies more than one location ID, the endpoint orders the result by location ID, and then by creation date within each location. If no locations are given in the query, all locations are searched.
Search terminal checkouts	Retrieves a filtered list of Terminal checkout requests created by the account making the request.
Search terminal refunds	Retrieves a filtered list of Interac Terminal refund requests created by the seller making the request.
Submit evidence	Submits evidence to the cardholder's bank. Before submitting evidence, Square compiles all available evidence. This includes evidence uploaded using the CreateDisputeEvidenceFile and CreateDisputeEvidenceText endpoints and evidence automatically provided by Square, when available.
Update customer	Updates a customer profile. To change an attribute, specify the new value. To remove an attribute, specify the value as an empty string or empty object.
Update customer group	Updates a customer group.
Update invoice	Updates an invoice by modifying fields, clearing fields, or both.
Update item modifier lists	Updates the CatalogModifierList objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item.
Update item taxes	Updates the CatalogTax objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item.
Update order (Beta)	Updates an open order by adding, replacing, or deleting fields. Orders with a COMPLETED or CANCELED state cannot be updated.
Update payment	Updates a payment with the APPROVED status. You can update the amount_money and tip_money using this endpoint.
Update subscription	Updates a subscription. You can set, modify, and clear the subscription field values.
Upsert catalog object	Creates or updates the target CatalogObject.

Accept dispute

Operation ID:

DisputeAccept

Accepts the loss on a dispute. Square returns the disputed amount to the cardholder and updates the dispute state to ACCEPTED. Square debits the disputed amount from the seller’s Square account. If the Square account does not have sufficient funds, Square debits the associated bank account.

Parameters

Name	Key	Required	Type	Description
Dispute ID	dispute_id	True	string	The identifier of the dispute.

Returns

Name	Path	Type	Description
ID	dispute.id	string	The unique, Square-issued identifier.
Amount	dispute.amount_money.amount	integer	The amount.
Currency	dispute.amount_money.currency	string	The currency.
Reason	dispute.reason	string	The reason for this object.
State	dispute.state	string	The current state.
Due At	dispute.due_at	string	The time when the next action is due, in RFC 3339 format.
Disputed Payments	dispute.disputed_payments	array of object
Payment ID	dispute.disputed_payments.payment_id	string	Square-generated unique ID of the payment.
Card Brand	dispute.card_brand	string	The card's brand.
Created At	dispute.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	dispute.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Brand Dispute ID	dispute.brand_dispute_id	string	The ID of the dispute in the card brand system, generated by the card brand.

Add group to customer

Operation ID:

CustomerAddGroup

Adds a group membership to a customer. The customer is identified by the customer_id value and the customer group is identified by the group_id value.

Parameters

Name	Key	Required	Type	Description
Customer ID	customer_id	True	string	The identifier of the customer.
Group ID	group_id	True	string	The identifier of the group.

Returns

response

object

Batch change inventory

Operation ID:

InventoryBatchChange

Applies adjustments and counts to the provided item quantities. On success: returns the current calculated counts for all objects referenced in the request.

Parameters

Name	Key	Required	Type	Description
Idempotency Key	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).
Type	type		string	The type of this object.
Reference ID	reference_id		string	An optional user-defined reference ID that associates this card with another entity in an external system.
Catalog Object ID	catalog_object_id		string	The Square-generated ID of the CatalogObject being tracked.
State	state		string	The current inventory state for the related quantity of items.
Location ID	location_id		string	The location ID for a recipient (other than the merchant) receiving a portion of this tender.
Quantity	quantity		string	The number of items affected by the physical count as a decimal string. The number can support up to 5 digits after the decimal point.
Employee ID	employee_id		string	The Square-generated ID of the Employee responsible for the physical count.
Occurred At	occurred_at		string	A client-generated RFC 3339-formatted timestamp that indicates when the physical count was examined. For physical count updates, the occurred_at timestamp cannot be older than 24 hours or in the future relative to the time of the request.
Ignore Unchanged Counts	ignore_unchanged_counts		boolean	Indicates whether the current physical count should be ignored if the quantity is unchanged since the last physical count.

Returns

Name	Path	Type	Description
Counts	counts	array of object
Catalog Object ID	counts.catalog_object_id	string	The Square-generated ID of the CatalogObject being tracked.
Catalog Object Type	counts.catalog_object_type	string	The type of the CatalogObject being tracked.
State	counts.state	string	The current state.
Location ID	counts.location_id	string	The identifier for the location.
Quantity	counts.quantity	string	The number of items affected by the estimated count as a decimal string. Can support up to 5 digits after the decimal point.
Calculated At	counts.calculated_at	string	An RFC 3339-formatted timestamp that indicates when the most recent physical count or adjustment affecting the estimated count is received.

Batch delete catalog objects

Operation ID:

CatalogBatchDelete

Deletes a set of CatalogItems based on the provided list of target IDs and returns a set of successfully deleted IDs in the response.

Parameters

Name	Key	Required	Type	Description
Object IDs	object_ids		array of string

Returns

Name	Path	Type	Description
Deleted Object IDs	deleted_object_ids	array of string
Deleted At	deleted_at	string	The database timestamp of this deletion in RFC 3339 format

Batch retrieve catalog objects

Operation ID:

CatalogBatchRetrieve

Returns a set of objects based on the provided ID. Each CatalogItem returned in the set includes all of its child information including: all of its CatalogItemVariation objects, references to its CatalogModifierList objects, and the ids of any CatalogTax objects that apply to it.

Parameters

Name	Key	Required	Type	Description
Object IDs	object_ids		array of string
Catalog Version	catalog_version		integer	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	include_related_objects		boolean	If true, the response will include additional objects that are related to the requested objects, as follows: If the objects field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects and CatalogModifierLists will be returned in the related_objects field of the response. If the objects field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in the related_objects field of the response.

Returns

Name	Path	Type	Description
Objects	objects	array of object
Type	objects.type	string	The type of this object.
ID	objects.id	string	The unique, Square-issued identifier.
Updated At	objects.updated_at	string	Last modification timestamp in RFC 3339 format
Version	objects.version	integer	The current version of the object.
Is Deleted	objects.is_deleted	boolean	If true, the object has been deleted from the database. Must be false for new objects being inserted. When deleted, the updated_at field will equal the deletion time.
Present at All Locations	objects.present_at_all_locations	boolean	If true, this object is present at all locations (including future locations), except where specified in the absent_at_location_ids field. If false, this object is not present at any locations (including future locations), except where specified in the present_at_location_ids field. If not specified, defaults to true.
Name	objects.item_data.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.
Description	objects.item_data.title	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.
Category ID	objects.item_data.category_id	string	The ID of the item's category, if any.
Tax IDs	objects.item_data.tax_ids	array of string
Variations	objects.item_data.variations	array of object
Type	objects.item_data.variations.type	string	The type of this object. Each object type has expected properties expressed in a structured format within its corresponding *_data field below.
ID	objects.item_data.variations.id	string	An identifier to reference this object.
Updated At	objects.item_data.variations.updated_at	string	Last modification timestamp in RFC 3339 format
Version	objects.item_data.variations.version	integer	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.
Is Deleted	objects.item_data.variations.is_deleted	boolean	If true, the object has been deleted from the database. Must be false for new objects being inserted. When deleted, the updated_at field will equal the deletion time.
Present At All Locations	objects.item_data.variations.present_at_all_locations	boolean	A list of locations where the object is present, even if present_at_all_locations is false. This can include locations that are deactivated.
Item ID	objects.item_data.variations.item_variation_data.item_id	string	The ID of the object with this item variation.
Name	objects.item_data.variations.item_variation_data.name	string	This item's name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.
Ordinal	objects.item_data.variations.item_variation_data.ordinal	integer	The order in which this item variation should be displayed. This value is read-only.
Pricing Type	objects.item_data.variations.item_variation_data.pricing_type	string	Indicates whether the item variation's price is fixed or determined at the time of sale.
Amount	objects.item_data.variations.item_variation_data.price_money.amount	integer	The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case.
Currency	objects.item_data.variations.item_variation_data.price_money.currency	string	The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.
Related Objects	related_objects	array of object
Type	related_objects.type	string	The type of this object.
ID	related_objects.id	string	The unique, Square-issued identifier.
Updated At	related_objects.updated_at	string	Last modification timestamp in RFC 3339 format
Version	related_objects.version	integer	The current version of the object.
Is Deleted	related_objects.is_deleted	boolean	If true, the object has been deleted from the database. Must be false for new objects being inserted. When deleted, the updated_at field will equal the deletion time.
Present at All Locations	related_objects.present_at_all_locations	boolean	If true, this object is present at all locations (including future locations), except where specified in the absent_at_location_ids field. If false, this object is not present at any locations (including future locations), except where specified in the present_at_location_ids field. If not specified, defaults to true.
Name	related_objects.category_data.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.
Name	related_objects.tax_data.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.
Calculation Phase	related_objects.tax_data.calculation_phase	string	Whether the tax is calculated based on a payment's subtotal or total.
Inclusion Type	related_objects.tax_data.inclusion_type	string	Whether the tax is ADDITIVE or INCLUSIVE.
Percentage	related_objects.tax_data.percentage	string	The percentage in decimal form, using a '.' as the decimal separator and without a '%' sign. A value of 7.5 corresponds to 7.5%.
Enabled	related_objects.tax_data.enabled	boolean	Indicates whether or not an object can be used.

Batch retrieve inventory changes

Operation ID:

InventoryBatchRetrieveChanges

Returns historical physical counts and adjustments based on the provided filter criteria.

Parameters

Name	Key	Required	Type	Description
Catalog Object IDs	catalog_object_ids		array of string
Location IDs	location_ids		array of string
Types	types		array of string
States	states		array of string
Updated After	updated_after		string	The filter to return results with their calculated_at value after the given time as specified in an RFC 3339 timestamp.
Updated Before	updated_before		string	The filter to return results with their created_at or calculated_at value strictly before the given time as specified in an RFC 3339 timestamp.

Returns

Name	Path	Type	Description
Changes	changes	array of object
Type	changes.type	string	The type of this object.
ID	changes.physical_count.id	string	The identifier of the object
Reference ID	changes.physical_count.reference_id	string	An optional user-defined reference ID that associates this card with another entity in an external system.
Catalog Object ID	changes.physical_count.catalog_object_id	string	The Square-generated ID of the CatalogObject being tracked.
Catalog Object Type	changes.physical_count.catalog_object_type	string	The type of the CatalogObject being tracked.
State	changes.physical_count.state	string	The current inventory state for the related quantity of items.
Location ID	changes.physical_count.location_id	string	The location ID for a recipient (other than the merchant) receiving a portion of this tender.
Quantity	changes.physical_count.quantity	string	The number of items affected by the physical count as a decimal string. The number can support up to 5 digits after the decimal point.
Product	changes.physical_count.source.product	string	Product type for the application.
Application ID	changes.physical_count.source.application_id	string	Square ID assigned to the application.
Name	changes.physical_count.source.name	string	The name of the item.
Employee ID	changes.physical_count.employee_id	string	The Square-generated ID of the Employee responsible for the physical count.
Occurred At	changes.physical_count.occurred_at	string	A client-generated RFC 3339-formatted timestamp that indicates when the physical count was examined. For physical count updates, the occurred_at timestamp cannot be older than 24 hours or in the future relative to the time of the request.
Created At	changes.physical_count.created_at	string	A client-generated RFC 3339-formatted timestamp that indicates when the physical count was created.

Batch retrieve inventory counts

Operation ID:

InventoryBatchRetrieveCounts

Returns current counts for the provided CatalogObjects at the requested Locations.

Parameters

Name	Key	Required	Type	Description
Catalog Object IDs	catalog_object_ids		array of string
Location IDs	location_ids		array of string
Updated After	updated_after		string	The filter to return results with their calculated_at value after the given time as specified in an RFC 3339 timestamp.

Returns

Name	Path	Type	Description
Counts	counts	array of object
Catalog Object ID	counts.catalog_object_id	string	The Square-generated ID of the CatalogObject being tracked.
Catalog Object Type	counts.catalog_object_type	string	The type of the CatalogObject being tracked.
State	counts.state	string	The current state.
Location ID	counts.location_id	string	The identifier for the location.
Quantity	counts.quantity	string	The number of items affected by the estimated count as a decimal string. Can support up to 5 digits after the decimal point.
Calculated At	counts.calculated_at	string	An RFC 3339-formatted timestamp that indicates when the most recent physical count or adjustment affecting the estimated count is received.

Batch retrieve orders

Operation ID:

OrderBatchRetrieve

Retrieves a set of orders by their IDs. If a given order ID does not exist, the ID is ignored instead of generating an error.

Parameters

Name	Key	Required	Type	Description
Location ID	location_id		string	The location identifier.
Order IDs	order_ids		array of string

Returns

Name	Path	Type	Description
Orders	orders	array of object
ID	orders.id	string	The unique, Square-issued identifier.
Location ID	orders.location_id	string	The identifier for the location.
Reference ID	orders.reference_id	string	An optional second ID used to associate the customer profile with an entity in another system.
Line Items	orders.line_items	array of object
UID	orders.line_items.uid	string	The Square-generated ID of the payment request in an invoice.
Name	orders.line_items.name	string	A human-readable name.
Quantity	orders.line_items.quantity	string	The quantity purchased, formatted as a decimal number.
Amount	orders.line_items.base_price_money.amount	integer	The amount.
Currency	orders.line_items.base_price_money.currency	string	The currency.
Amount	orders.line_items.total_money.amount	integer	The amount.
Currency	orders.line_items.total_money.currency	string	The currency.
Amount	orders.total_money.amount	integer	The amount.
Currency	orders.total_money.currency	string	The currency.

Batch upsert catalog objects

Operation ID:

CatalogBatchUpsert

Creates or updates up to 10,000 target objects based on the provided list of objects. The target objects are grouped into batches and each batch is inserted/updated in an all-or-nothing manner. If an object within a batch is malformed in some way, or violates a database constraint, the entire batch containing that item will be disregarded. However, other batches in the same request may still succeed. Each batch may contain up to 1,000 objects, and batches will be processed in order as long as the total object count for the request (items, variations, modifier lists, discounts, and taxes) is no more than 10,000.

Parameters

Name	Key	Required	Type	Description
Idempotency Key	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).
Type	type		string	The type of this object.
ID	id		string	An identifier to reference this object.
Present at All Locations	present_at_all_locations		boolean	If true, this object is present at all locations (including future locations), except where specified in the absent_at_location_ids field. If false, this object is not present at any locations (including future locations), except where specified in the present_at_location_ids field. If not specified, defaults to true.
Name	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.
Description	title		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.
Category ID	category_id		string	The ID of the item's category, if any.
Tax IDs	tax_ids		array of string
Type	type		string	The type of this object. Each object type has expected properties expressed in a structured format within its corresponding *_data field below.
ID	id		string	An identifier to reference this object.
Present At All Locations	present_at_all_locations		boolean	Whether present at all locations.
Item ID	item_id		string	The identifier of the item.
Name	name		string	The name of the item.
Pricing Type	pricing_type		string	The type of pricing.
Amount	amount		integer	The amount.
Currency	currency		string	The currency.
Name	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.
Name	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.
Calculation Phase	calculation_phase		string	Whether the tax is calculated based on a payment's subtotal or total.
Inclusion Type	inclusion_type		string	Whether the tax is ADDITIVE or INCLUSIVE.
Percentage	percentage		string	The percentage of the tax in decimal form, using a '.' as the decimal separator and without a '%' sign. A value of 7.5 corresponds to 7.5%.
Applies to Custom Amounts	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 particular CatalogItem.
Enabled	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).

Returns

Name	Path	Type	Description
Objects	objects	array of object
Type	objects.type	string	The type of this object.
ID	objects.id	string	The unique, Square-issued identifier.
Updated At	objects.updated_at	string	Last modification timestamp in RFC 3339 format
Version	objects.version	integer	The current version of the object.
Is Deleted	objects.is_deleted	boolean	If true, the object has been deleted from the database. Must be false for new objects being inserted. When deleted, the updated_at field will equal the deletion time.
Present at All Locations	objects.present_at_all_locations	boolean	If true, this object is present at all locations (including future locations), except where specified in the absent_at_location_ids field. If false, this object is not present at any locations (including future locations), except where specified in the present_at_location_ids field. If not specified, defaults to true.
Name	objects.item_data.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.
Description	objects.item_data.title	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.
Category ID	objects.item_data.category_id	string	The ID of the item's category, if any.
Tax IDs	objects.item_data.tax_ids	array of string
Variations	objects.item_data.variations	array of object
Type	objects.item_data.variations.type	string	The type of this object. Each object type has expected properties expressed in a structured format within its corresponding *_data field below.
ID	objects.item_data.variations.id	string	An identifier to reference this object.
Updated At	objects.item_data.variations.updated_at	string	Last modification timestamp in RFC 3339 format
Version	objects.item_data.variations.version	integer	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.
Is Deleted	objects.item_data.variations.is_deleted	boolean	If true, the object has been deleted from the database. Must be false for new objects being inserted. When deleted, the updated_at field will equal the deletion time.
Present At All Locations	objects.item_data.variations.present_at_all_locations	boolean	A list of locations where the object is present, even if present_at_all_locations is false. This can include locations that are deactivated.
Item ID	objects.item_data.variations.item_variation_data.item_id	string	The ID of the object with this item variation.
Name	objects.item_data.variations.item_variation_data.name	string	This item's name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.
Ordinal	objects.item_data.variations.item_variation_data.ordinal	integer	The order in which this item variation should be displayed. This value is read-only.
Pricing Type	objects.item_data.variations.item_variation_data.pricing_type	string	Indicates whether the item variation's price is fixed or determined at the time of sale.
Amount	objects.item_data.variations.item_variation_data.price_money.amount	integer	The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case.
Currency	objects.item_data.variations.item_variation_data.price_money.currency	string	The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.
Name	objects.category_data.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.
Name	objects.tax_data.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.
Calculation Phase	objects.tax_data.calculation_phase	string	Whether the tax is calculated based on a payment's subtotal or total.
Inclusion Type	objects.tax_data.inclusion_type	string	Whether the tax is ADDITIVE or INCLUSIVE.
Percentage	objects.tax_data.percentage	string	The percentage in decimal form, using a '.' as the decimal separator and without a '%' sign. A value of 7.5 corresponds to 7.5%.
Applies To Custom Amounts	objects.tax_data.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 particular CatalogItem.
Enabled	objects.tax_data.enabled	boolean	Indicates whether or not an object can be used.
ID Mappings	id_mappings	array of object
Client Object ID	id_mappings.client_object_id	string	The client-supplied temporary #-prefixed ID for a new CatalogObject.
Object ID	id_mappings.object_id	string	The permanent ID created by the server.

Calculate order (Beta)

Operation ID:

OrderCalculate

Enables applications to preview order pricing without creating an order.

Parameters

Name	Key	Required	Type	Description
Idempotency Key	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).
Location ID	location_id		string	The identifier of the location.
Name	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.
Percentage	percentage		string	The percentage in decimal form, using a '.' as the decimal separator and without a '%' sign. A value of 7.5 corresponds to 7.5%.
Scope	scope		string	Indicates the current level.
Name	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.
Quantity	quantity		string	The number of items affected by the physical count as a decimal string. The number can support up to 5 digits after the decimal point.
Amount	amount		integer	The amount.
Currency	currency		string	The currency.

Returns

Name	Path	Type	Description
Location ID	order.location_id	string	The identifier of the location.
Line Items	order.line_items	array of object
UID	order.line_items.uid	string	The Square-generated ID.
Quantity	order.line_items.quantity	string	The number of items affected by the physical count as a decimal string. The number can support up to 5 digits after the decimal point.
Name	order.line_items.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.
Amount	order.line_items.base_price_money.amount	integer	The amount.
Currency	order.line_items.base_price_money.currency	string	The currency.
Amount	order.line_items.gross_sales_money.amount	integer	The amount.
Currency	order.line_items.gross_sales_money.currency	string	The currency.
Amount	order.line_items.total_tax_money.amount	integer	The amount.
Currency	order.line_items.total_tax_money.currency	string	The currency.
Amount	order.line_items.total_discount_money.amount	integer	The amount.
Currency	order.line_items.total_discount_money.currency	string	The currency.
Amount	order.line_items.total_money.amount	integer	The amount.
Currency	order.line_items.total_money.currency	string	The currency.
Amount	order.line_items.variation_total_price_money.amount	integer	The amount.
Currency	order.line_items.variation_total_price_money.currency	string	The currency.
Applied Discounts	order.line_items.applied_discounts	array of object
UID	order.line_items.applied_discounts.uid	string	A Square-assigned ID.
Discount UID	order.line_items.applied_discounts.discount_uid	string	The uid of the discount that the applied discount represents.
Amount	order.line_items.applied_discounts.applied_money.amount	integer	The amount.
Currency	order.line_items.applied_discounts.applied_money.currency	string	The currency.
Discounts	order.discounts	array of object
UID	order.discounts.uid	string	The Square-generated ID.
Name	order.discounts.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.
Percentage	order.discounts.percentage	string	The percentage in decimal form, using a '.' as the decimal separator and without a '%' sign. A value of 7.5 corresponds to 7.5%.
Amount	order.discounts.applied_money.amount	integer	The amount.
Currency	order.discounts.applied_money.currency	string	The currency.
Type	order.discounts.type	string	Indicates the type.
Scope	order.discounts.scope	string	Indicates the current level.
Created At	order.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	order.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
State	order.state	string	The current state.
Version	order.version	integer	The current version of this object.
Amount	order.total_tax_money.amount	integer	The amount.
Currency	order.total_tax_money.currency	string	The currency.
Amount	order.total_discount_money.amount	integer	The amount.
Currency	order.total_discount_money.currency	string	The currency.
Amount	order.total_tip_money.amount	integer	The amount.
Currency	order.total_tip_money.currency	string	The currency.
Amount	order.total_money.amount	integer	The amount.
Currency	order.total_money.currency	string	The currency.
Amount	order.total_service_charge_money.amount	integer	The amount.
Currency	order.total_service_charge_money.currency	string	The currency.
Amount	order.net_amounts.total_money.amount	integer	The amount.
Currency	order.net_amounts.total_money.currency	string	The currency.
Amount	order.net_amounts.tax_money.amount	integer	The amount.
Currency	order.net_amounts.tax_money.currency	string	The currency.
Amount	order.net_amounts.discount_money.amount	integer	The amount.
Currency	order.net_amounts.discount_money.currency	string	The currency.
Amount	order.net_amounts.tip_money.amount	integer	The amount.
Currency	order.net_amounts.tip_money.currency	string	The currency.
Amount	order.net_amounts.service_charge_money.amount	integer	The amount.
Currency	order.net_amounts.service_charge_money.currency	string	The currency.

Cancel invoice

Operation ID:

InvoiceCancel

Cancels an invoice. The seller cannot collect payments for the canceled invoice.

Parameters

Name	Key	Required	Type	Description
Invoice ID	invoice_id	True	string	The identifier of the invoice.
Version	version		integer	The version.

Returns

Name	Path	Type	Description
ID	invoice.id	string	The unique, Square-issued identifier.
Version	invoice.version	integer	The current version of this object.
Location ID	invoice.location_id	string	The identifier of the location.
Order ID	invoice.order_id	string	The ID of the order.
Payment Requests	invoice.payment_requests	array of object
UID	invoice.payment_requests.uid	string	The Square-generated ID.
Request Type	invoice.payment_requests.request_type	string	Identifies the payment request type. This type defines how the payment request amount is determined.
Due Date	invoice.payment_requests.due_date	string	The due date for the payment request, in YYYY-MM-DD format.
Tipping Enabled	invoice.payment_requests.tipping_enabled	boolean	If set to true, provides a place for the customer to pay a tip.
Reminders	invoice.payment_requests.reminders	array of object
UID	invoice.payment_requests.reminders.uid	string	A Square-assigned ID.
Relative Scheduled Days	invoice.payment_requests.reminders.relative_scheduled_days	integer	The number of days before (a negative number) or after (a positive number) the payment request due_date when the reminder is sent.
Message	invoice.payment_requests.reminders.message	string	The message.
Status	invoice.payment_requests.reminders.status	string	The current status.
Amount	invoice.payment_requests.computed_amount_money.amount	integer	The amount.
Currency	invoice.payment_requests.computed_amount_money.currency	string	The currency.
Amount	invoice.payment_requests.total_completed_amount_money.amount	integer	The amount.
Currency	invoice.payment_requests.total_completed_amount_money.currency	string	The currency.
Automatic Payment Source	invoice.payment_requests.automatic_payment_source	string	The payment method for an automatic payment.
Invoice Number	invoice.invoice_number	string	A user-friendly invoice number. The value is unique within a location. If not provided when creating an invoice, Square assigns a value.
Title	invoice.title	string	The title.
Description	invoice.description	string	The description.
Scheduled At	invoice.scheduled_at	string	The timestamp when the processing is scheduled, in RFC 3339 format.
Status	invoice.status	string	The current verification status of this object.
Timezone	invoice.timezone	string	The time zone used to interpret calendar dates. When an invoice is created, this field is set to the timezone specified for the seller location. The value cannot be changed.
Created At	invoice.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	invoice.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Customer ID	invoice.primary_recipient.customer_id	string	The ID of the customer associated with the order.
Given Name	invoice.primary_recipient.given_name	string	The recipient's given (that is, first) name.
Family Name	invoice.primary_recipient.family_name	string	The recipient's family (that is, last) name.
Email Address	invoice.primary_recipient.email_address	string	The recipient's email address.
Phone Number	invoice.primary_recipient.phone_number	string	The recipient's phone number.
Card	invoice.accepted_payment_methods.card	boolean	Indicates whether credit card or debit card payments are accepted.
Square Gift Card	invoice.accepted_payment_methods.square_gift_card	boolean	Indicates whether Square gift card payments are accepted.
Bank Account	invoice.accepted_payment_methods.bank_account	boolean	Indicates whether bank transfer payments are accepted.
Custom Fields	invoice.custom_fields	array of object
Label	invoice.custom_fields.label	string	The label or title of the custom field.
Value	invoice.custom_fields.value	string	The text of the custom field.
Placement	invoice.custom_fields.placement	string	The location of the custom field on the invoice.
Delivery Method	invoice.delivery_method	string	The delivery method that Square uses to send the invoice, reminders, and receipts to the customer. After the invoice is published, Square processes the invoice based on the delivery method and payment request settings, either immediately or on the scheduled_at date, if specified.
Sale or Service Date	invoice.sale_or_service_date	string	The date of the sale or the date that the service is rendered, in YYYY-MM-DD format. This field can be used to specify a past or future date which is displayed on the invoice.

Cancel payment

Operation ID:

PaymentCancel

Cancels (voids) a payment. You can use this endpoint to cancel a payment with the APPROVED status.

Parameters

Name	Key	Required	Type	Description
Payment ID	payment_id	True	string	The identifier of the payment.

Returns

Name	Path	Type	Description
ID	payment.id	string	The unique, Square-issued identifier.
Created At	payment.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	payment.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Amount	payment.amount_money.amount	integer	The amount.
Currency	payment.amount_money.currency	string	The currency.
Amount	payment.tip_money.amount	integer	The amount.
Currency	payment.tip_money.currency	string	The currency.
Status	payment.status	string	The current verification status of this object.
Delay Duration	payment.delay_duration	string	The duration of time after the payment's creation when Square automatically applies the delay_action to the payment. This automatic delay_action applies only to payments that do not reach a terminal state (COMPLETED, CANCELED, or FAILED) before the delay_duration time period. This field is specified as a time duration, in RFC 3339 format.
Source Type	payment.source_type	string	The source type for this payment. Current values include CARD, BANK_ACCOUNT, WALLET, CASH, or EXTERNAL.
Status	payment.card_details.status	string	The current status.
Card Brand	payment.card_details.card.card_brand	string	The card's brand.
Last 4	payment.card_details.card.last_4	string	The last 4 digits of the card number.
Exp Month	payment.card_details.card.exp_month	integer	The expiration month of the associated card as an integer between 1 and 12.
Exp Year	payment.card_details.card.exp_year	integer	The four-digit year of the card's expiration date.
Fingerprint	payment.card_details.card.fingerprint	string	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
Card Type	payment.card_details.card.card_type	string	The type of the card.
Prepaid Type	payment.card_details.card.prepaid_type	string	Indicates whether the Card is prepaid or not.
BIN	payment.card_details.card.bin	string	The first six digits of the card number, known as the Bank Identification Number (BIN).
Entry Method	payment.card_details.entry_method	string	The method used to enter the card's details for the payment. The method can be KEYED, SWIPED, EMV, ON_FILE, or CONTACTLESS.
CVV Status	payment.card_details.cvv_status	string	The status code returned from the Card Verification Value (CVV) check. The code can be CVV_ACCEPTED, CVV_REJECTED, or CVV_NOT_CHECKED.
AVS Status	payment.card_details.avs_status	string	The status code returned from the Address Verification System (AVS) check. The code can be AVS_ACCEPTED, AVS_REJECTED, or AVS_NOT_CHECKED.
Auth Result Code	payment.card_details.auth_result_code	string	The status code returned by the card issuer that describes the payment's authorization status.
Statement Description	payment.card_details.statement_description	string	The statement description sent to the card networks.
Authorized At	payment.card_details.card_payment_timeline.authorized_at	string	The timestamp when the payment was authorized, in RFC 3339 format.
Voided At	payment.card_details.card_payment_timeline.voided_at	string	The timestamp when the payment was voided, in RFC 3339 format.
Location ID	payment.location_id	string	The identifier of the location.
Order ID	payment.order_id	string	The ID of the order.
Created At	payment.risk_evaluation.created_at	string	The timestamp when created, in RFC 3339 format.
Risk Level	payment.risk_evaluation.risk_level	string	The risk level associated with the payment.
Note	payment.note	string	A custom note associated with the customer profile.
Customer ID	payment.customer_id	string	The ID of this object representing the customer.
Amount	payment.total_money.amount	integer	The amount.
Currency	payment.total_money.currency	string	The currency.
Amount	payment.approved_money.amount	integer	The amount.
Currency	payment.approved_money.currency	string	The currency.
Delay Action	payment.delay_action	string	The action to be applied to the payment when the delay_duration has elapsed.
Delayed Until	payment.delayed_until	string	The read-only timestamp of when the delay_action is automatically applied, in RFC 3339 format.
Square Product	payment.application_details.square_product	string	The Square product, such as Square Point of Sale (POS), Square Invoices, or Square Virtual Terminal.
Application ID	payment.application_details.application_id	string	Read-only Square ID assigned to the application.
Version Token	payment.version_token	string	This opaque token identifies a specific version of the object.

Cancel payment by idempotency key

Operation ID:

PaymentCancelIdempotency

Cancels (voids) a payment identified by the idempotency key that is specified in the request. Use this method when the status of a CreatePayment request is unknown (for example, after you send a CreatePayment request, a network error occurs and you do not get a response). In this case, you can direct Square to cancel the payment using this endpoint. In the request, you provide the same idempotency key that you provided in your CreatePayment request that you want to cancel. After canceling the payment, you can submit your CreatePayment request again. Note that if no payment with the specified idempotency key is found, no action is taken and the endpoint returns successfully.

Parameters

Name	Key	Required	Type	Description
Idempotency Key	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).

Returns

response

object

Cancel subscription

Operation ID:

SubscriptionCancel

Sets the canceled_date field to the end of the active billing period. After this date, the status changes from ACTIVE to CANCELED.

Parameters

Name	Key	Required	Type	Description
Subscription ID	subscription_id	True	string	The identifier of the subscription.

Returns

Name	Path	Type	Description
ID	subscription.id	string	The unique, Square-issued identifier.
Location ID	subscription.location_id	string	The identifier of the location.
Plan ID	subscription.plan_id	string	The ID of the associated subscription plan.
Customer ID	subscription.customer_id	string	The ID of this object representing the customer.
Card ID	subscription.card_id	string	The ID of the customer card that is charged for the subscription.
Start Date	subscription.start_date	string	The start date of the subscription, in YYYY-MM-DD format.
Canceled Date	subscription.canceled_date	string	The subscription cancellation date, in YYYY-MM-DD format.
Paid Until Date	subscription.paid_until_date	string	The date paid until.
Status	subscription.status	string	The current verification status of this object.
Created At	subscription.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Version	subscription.version	integer	The current version of this object.
Timezone	subscription.timezone	string	The time zone used to interpret calendar dates. When an invoice is created, this field is set to the timezone specified for the seller location. The value cannot be changed.
Name	subscription.source.name	string	The name.

Cancel terminal checkout

Operation ID:

TerminalCancelCheckout

Cancels a Terminal checkout request if the status of the request permits it.

Parameters

Name	Key	Required	Type	Description
Checkout ID	checkout_id	True	string	The identifier of the checkout.

Returns

Name	Path	Type	Description
ID	checkout.id	string	The unique, Square-issued identifier.
Amount	checkout.amount_money.amount	integer	The amount.
Currency	checkout.amount_money.currency	string	The currency.
Reference ID	checkout.reference_id	string	An optional user-defined reference ID.
Device ID	checkout.device_options.device_id	string	The unique ID of the device intended for this TerminalCheckout.
Allow Tipping	checkout.device_options.tip_settings.allow_tipping	boolean	Indicates whether tipping is enabled for this checkout. Defaults to false.
Skip Receipt Screen	checkout.device_options.skip_receipt_screen	boolean	Instructs the device to skip the receipt screen. Defaults to false.
Status	checkout.status	string	The current verification status of this object.
Cancel Reason	checkout.cancel_reason	string	The reason for the cancelled transaction.
Created At	checkout.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	checkout.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
App ID	checkout.app_id	string	The ID of the application that created the checkout.
Deadline Duration	checkout.deadline_duration	string	An RFC 3339 duration, after which the checkout is automatically canceled. A TerminalCheckout that is PENDING is automatically CANCELED and has a cancellation reason of TIMED_OUT. Default: 5 minutes from creation

Cancel terminal refund

Operation ID:

TerminalCancelRefund

Cancels an Interac Terminal refund request by refund request ID if the status of the request permits it.

Parameters

Name	Key	Required	Type	Description
Terminal Refund ID	terminal_refund_id	True	string	The identifier of the terminal refund.

Returns

Name	Path	Type	Description
ID	refund.id	string	The unique, Square-issued identifier.
Payment ID	refund.payment_id	string	The unique ID of the payment.
Amount	refund.amount_money.amount	integer	The amount.
Currency	refund.amount_money.currency	string	The currency.
Reason	refund.reason	string	The reason for this object.
Device ID	refund.device_id	string	The unique ID of the device intended for this TerminalRefund.
Deadline Duration	refund.deadline_duration	string	An RFC 3339 duration, after which the checkout is automatically canceled. A TerminalCheckout that is PENDING is automatically CANCELED and has a cancellation reason of TIMED_OUT. Default: 5 minutes from creation
Status	refund.status	string	The current verification status of this object.
Cancel Reason	refund.cancel_reason	string	The reason for the cancelled transaction.
Created At	refund.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	refund.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
App ID	refund.app_id	string	The ID of the application that created the checkout.
Card Brand	refund.card.card_brand	string	The brand of the card.
last_4	refund.card.last_4	string	The last 4 digits of the card number.
Exp Month	refund.card.exp_month	integer	The expiration month of the associated card as an integer between 1 and 12.
Exp Year	refund.card.exp_year	integer	The four-digit year of the card's expiration date.
Fingerprint	refund.card.fingerprint	string	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
Card Type	refund.card.card_type	string	The type of the card.
BIN	refund.card.bin	string	The first six digits of the card number, known as the Bank Identification Number (BIN).
Order ID	refund.order_id	string	The ID of the order.
Location ID	refund.location_id	string	The identifier of the location.

Catalog info

Operation ID:

CatalogInfo

Retrieves information about the Square Catalog API, such as batch size limits that can be used by the BatchUpsertCatalogObjects endpoint.

Returns

Name	Path	Type	Description
Batch Upsert Max Objects per Batch	limits.batch_upsert_max_objects_per_batch	integer	The maximum number of objects that may appear within a single batch in a /v2/catalog/batch-upsert request.
Batch Upsert Max Total Objects	limits.batch_upsert_max_total_objects	integer	The maximum number of objects that may appear across all batches in a /v2/catalog/batch-upsert request.
Batch Retrieve Max Object IDs	limits.batch_retrieve_max_object_ids	integer	The maximum number of object IDs that may appear in a /v2/catalog/batch-retrieve request.
Search Max Page Limit	limits.search_max_page_limit	integer	The maximum number of results that may be returned in a page of a /v2/catalog/search response.
Batch Delete Max Object IDs	limits.batch_delete_max_object_ids	integer	The maximum number of object IDs that may be included in a single /v2/catalog/batch-delete request.
Update Item Taxes Max Item IDs	limits.update_item_taxes_max_item_ids	integer	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 Enable	limits.update_item_taxes_max_taxes_to_enable	integer	The maximum number of tax IDs to be enabled that may be included in a single /v2/catalog/update-item-taxes request.
Update Item Taxes Max Taxes to Disable	limits.update_item_taxes_max_taxes_to_disable	integer	The maximum number of tax IDs to be disabled that may be included in a single /v2/catalog/update-item-taxes request.
Update Item Modifier Lists Max Item IDs	limits.update_item_modifier_lists_max_item_ids	integer	The maximum number of tax IDs to be disabled that may be included in a single /v2/catalog/update-item-taxes request.
Update Item Modifier Lists Max Modifier Lists to Enable	limits.update_item_modifier_lists_max_modifier_lists_to_enable	integer	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 Modifier Lists Max Modifier Lists to Disable	limits.update_item_modifier_lists_max_modifier_lists_to_disable	integer	The maximum number of modifier list IDs to be disabled that may be included in a single /v2/catalog/update-item-modifier-lists request.

Clone order (Beta)

Operation ID:

OrderClone

Creates a new order, in the DRAFT state, by duplicating an existing order. The newly created order has only the core fields (such as line items, taxes, and discounts) copied from the original order.

Parameters

Name	Key	Required	Type	Description
Order ID	order_id		string	The order identifier.
Version	version		integer	The version.
Idempotency Key	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).

Returns

Name	Path	Type	Description
ID	order.id	string	The unique, Square-issued identifier.
Location ID	order.location_id	string	The identifier of the location.
Line Items	order.line_items	array of object
UID	order.line_items.uid	string	The Square-generated ID.
Name	order.line_items.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.
Quantity	order.line_items.quantity	string	The number of items affected by the physical count as a decimal string. The number can support up to 5 digits after the decimal point.
Applied Taxes	order.line_items.applied_taxes	array of object
UID	order.line_items.applied_taxes.uid	string	A Square-assigned ID.
Tax UID	order.line_items.applied_taxes.tax_uid	string	The UID of the tax for which this applied tax represents.
Amount	order.line_items.applied_taxes.applied_money.amount	integer	The amount.
Currency	order.line_items.applied_taxes.applied_money.currency	string	The currency.
Applied Discounts	order.line_items.applied_discounts	array of object
UID	order.line_items.applied_discounts.uid	string	A Square-assigned ID.
Discount UID	order.line_items.applied_discounts.discount_uid	string	The uid of the discount that the applied discount represents.
Amount	order.line_items.applied_discounts.applied_money.amount	integer	The amount.
Currency	order.line_items.applied_discounts.applied_money.currency	string	The currency.
Amount	order.line_items.base_price_money.amount	integer	The amount.
Currency	order.line_items.base_price_money.currency	string	The currency.
Amount	order.line_items.gross_sales_money.amount	integer	The amount.
Currency	order.line_items.gross_sales_money.currency	string	The currency.
Amount	order.line_items.total_tax_money.amount	integer	The amount.
Currency	order.line_items.total_tax_money.currency	string	The currency.
Amount	order.line_items.total_discount_money.amount	integer	The amount.
Currency	order.line_items.total_discount_money.currency	string	The currency.
Amount	order.line_items.total_money.amount	integer	The amount.
Currency	order.line_items.total_money.currency	string	The currency.
Amount	order.line_items.variation_total_price_money.amount	integer	The amount.
Currency	order.line_items.variation_total_price_money.currency	string	The currency.
Catalog Object ID	order.line_items.catalog_object_id	string	The Square-generated ID of the CatalogObject being tracked.
Variation Name	order.line_items.variation_name	string	The name of the variation applied to this line item.
Modifiers	order.line_items.modifiers	array of object
UID	order.line_items.modifiers.uid	string	A Square-assigned ID.
Catalog Object ID	order.line_items.modifiers.catalog_object_id	string	The catalog object ID.
Name	order.line_items.modifiers.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.
Amount	order.line_items.modifiers.base_price_money.amount	integer	The amount.
Currency	order.line_items.modifiers.base_price_money.currency	string	The currency.
Amount	order.line_items.modifiers.total_price_money.amount	integer	The amount.
Currency	order.line_items.modifiers.total_price_money.currency	string	The currency.
Taxes	order.taxes	array of object
UID	order.taxes.uid	string	The Square-generated ID.
Name	order.taxes.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.
Type	order.taxes.type	string	Indicates the type.
Percentage	order.taxes.percentage	string	The percentage in decimal form, using a '.' as the decimal separator and without a '%' sign. A value of 7.5 corresponds to 7.5%.
Amount	order.taxes.applied_money.amount	integer	The amount.
Currency	order.taxes.applied_money.currency	string	The currency.
Scope	order.taxes.scope	string	Indicates the current level.
Discounts	order.discounts	array of object
UID	order.discounts.uid	string	The Square-generated ID.
Catalog Object ID	order.discounts.catalog_object_id	string	The Square-generated ID of the CatalogObject being tracked.
Name	order.discounts.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.
Type	order.discounts.type	string	Indicates the type.
Percentage	order.discounts.percentage	string	The percentage in decimal form, using a '.' as the decimal separator and without a '%' sign. A value of 7.5 corresponds to 7.5%.
Amount	order.discounts.applied_money.amount	integer	The amount.
Currency	order.discounts.applied_money.currency	string	The currency.
Scope	order.discounts.scope	string	Indicates the current level.
Amount	order.discounts.amount_money.amount	integer	The amount.
Currency	order.discounts.amount_money.currency	string	The currency.
Created At	order.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	order.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
State	order.state	string	The current state.
Version	order.version	integer	The current version of this object.
Reference ID	order.reference_id	string	An optional user-defined reference ID.
Amount	order.total_money.amount	integer	The amount.
Currency	order.total_money.currency	string	The currency.
Amount	order.total_tax_money.amount	integer	The amount.
Currency	order.total_tax_money.currency	string	The currency.
Amount	order.total_discount_money.amount	integer	The amount.
Currency	order.total_discount_money.currency	string	The currency.
Amount	order.total_tip_money.amount	integer	The amount.
Currency	order.total_tip_money.currency	string	The currency.
Amount	order.total_service_charge_money.amount	integer	The amount.
Currency	order.total_service_charge_money.currency	string	The currency.
Amount	order.net_amounts.total_money.amount	integer	The amount.
Currency	order.net_amounts.total_money.currency	string	The currency.
Amount	order.net_amounts.tax_money.amount	integer	The amount.
Currency	order.net_amounts.tax_money.currency	string	The currency.
Amount	order.net_amounts.discount_money.amount	integer	The amount.
Currency	order.net_amounts.discount_money.currency	string	The currency.
Amount	order.net_amounts.tip_money.amount	integer	The amount.
Currency	order.net_amounts.tip_money.currency	string	The currency.
Amount	order.net_amounts.service_charge_money.amount	integer	The amount.
Currency	order.net_amounts.service_charge_money.currency	string	The currency.
Name	order.source.name	string	The name.

Complete payment

Operation ID:

PaymentComplete

Completes (captures) a payment. By default, payments are set to complete immediately after they are created.

Parameters

Name	Key	Required	Type	Description
Payment ID	payment_id	True	string	The identifier of the payment.

Returns

Name	Path	Type	Description
ID	payment.id	string	The unique, Square-issued identifier.
Created At	payment.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	payment.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Amount	payment.amount_money.amount	integer	The amount.
Currency	payment.amount_money.currency	string	The currency.
Status	payment.status	string	The current verification status of this object.
Delay Duration	payment.delay_duration	string	The duration of time after the payment's creation when Square automatically applies the delay_action to the payment. This automatic delay_action applies only to payments that do not reach a terminal state (COMPLETED, CANCELED, or FAILED) before the delay_duration time period. This field is specified as a time duration, in RFC 3339 format.
Source Type	payment.source_type	string	The source type for this payment. Current values include CARD, BANK_ACCOUNT, WALLET, CASH, or EXTERNAL.
Status	payment.card_details.status	string	The current status.
Card Brand	payment.card_details.card.card_brand	string	The card's brand.
Last 4	payment.card_details.card.last_4	string	The last 4 digits of the card number.
Exp Month	payment.card_details.card.exp_month	integer	The expiration month of the associated card as an integer between 1 and 12.
Exp Year	payment.card_details.card.exp_year	integer	The four-digit year of the card's expiration date.
Fingerprint	payment.card_details.card.fingerprint	string	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
Card Type	payment.card_details.card.card_type	string	The type of the card.
Prepaid Type	payment.card_details.card.prepaid_type	string	Indicates whether the Card is prepaid or not.
BIN	payment.card_details.card.bin	string	The first six digits of the card number, known as the Bank Identification Number (BIN).
Entry Method	payment.card_details.entry_method	string	The method used to enter the card's details for the payment. The method can be KEYED, SWIPED, EMV, ON_FILE, or CONTACTLESS.
CVV Status	payment.card_details.cvv_status	string	The status code returned from the Card Verification Value (CVV) check. The code can be CVV_ACCEPTED, CVV_REJECTED, or CVV_NOT_CHECKED.
AVS Status	payment.card_details.avs_status	string	The status code returned from the Address Verification System (AVS) check. The code can be AVS_ACCEPTED, AVS_REJECTED, or AVS_NOT_CHECKED.
Auth Result Code	payment.card_details.auth_result_code	string	The status code returned by the card issuer that describes the payment's authorization status.
Statement Description	payment.card_details.statement_description	string	The statement description sent to the card networks.
Authorized At	payment.card_details.card_payment_timeline.authorized_at	string	The timestamp when the payment was authorized, in RFC 3339 format.
Captured At	payment.card_details.card_payment_timeline.captured_at	string	The timestamp when the payment was captured, in RFC 3339 format.
Location ID	payment.location_id	string	The identifier of the location.
Order ID	payment.order_id	string	The ID of the order.
Processing Fee	payment.processing_fee	array of object
Effective At	payment.processing_fee.effective_at	string	The timestamp of when the fee takes effect, in RFC 3339 format.
Type	payment.processing_fee.type	string	Indicates the type.
Amount	payment.processing_fee.amount_money.amount	integer	The amount.
Currency	payment.processing_fee.amount_money.currency	string	The currency.
Note	payment.note	string	A custom note associated with the customer profile.
Amount	payment.total_money.amount	integer	The amount.
Currency	payment.total_money.currency	string	The currency.
Amount	payment.approved_money.amount	integer	The amount.
Currency	payment.approved_money.currency	string	The currency.
Employee ID	payment.employee_id	string	The Square-generated ID of the Employee.
Receipt Number	payment.receipt_number	string	The payment's receipt number. The field is missing if a payment is canceled.
Receipt URL	payment.receipt_url	string	The URL for the payment's receipt. The field is only populated for COMPLETED payments.
Delay Action	payment.delay_action	string	The action to be applied to the payment when the delay_duration has elapsed.
Delayed Until	payment.delayed_until	string	The read-only timestamp of when the delay_action is automatically applied, in RFC 3339 format.
Team Member ID	payment.team_member_id	string	The ID of the team member.
Square Product	payment.application_details.square_product	string	The Square product, such as Square Point of Sale (POS), Square Invoices, or Square Virtual Terminal.
Application ID	payment.application_details.application_id	string	Read-only Square ID assigned to the application.
Version Token	payment.version_token	string	This opaque token identifies a specific version of the object.

Create card

Operation ID:

CardCreate

Adds a card on file to an existing merchant.

Parameters

Name	Key	Required	Type	Description
Idempotency Key	idempotency_key		string	The idempotency key.
Source ID	source_id		string	The identifier of the source.
Address Line 1	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.
Address Line 2	address_line_2		string	The second line of the address, if any.
Locality	locality		string	The city or town of the address.
Administrative District Level 1	administrative_district_level_1		string	A civil entity within the address's country. In the US, this is the state.
Postal Code	postal_code		string	The address's postal code.
Country	country		string	The address's country, in ISO 3166-1-alpha-2 format.
Cardholder Name	cardholder_name		string	The name of the cardholder.
Customer ID	customer_id		string	The ID of this object representing the customer.
Reference ID	reference_id		string	An optional user-defined reference ID.

Returns

Name	Path	Type	Description
ID	card.id	string	The unique, Square-issued identifier.
Address Line 1	card.billing_address.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.
Address Line 2	card.billing_address.address_line_2	string	The second line of the address, if any.
Locality	card.billing_address.locality	string	The city or town of the address.
Administrative District Level 1	card.billing_address.administrative_district_level_1	string	A civil entity within the address's country. In the US, this is the state.
Postal Code	card.billing_address.postal_code	string	The address's postal code.
Country	card.billing_address.country	string	The address's country, in ISO 3166-1-alpha-2 format.
Fingerprint	card.fingerprint	string	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
BIN	card.bin	string	The first six digits of the card number, known as the Bank Identification Number (BIN).
Card Brand	card.card_brand	string	The card's brand.
Card Type	card.card_type	string	The type of the card.
Cardholder Name	card.cardholder_name	string	The name of the cardholder.
Customer ID	card.customer_id	string	The ID of this object representing the customer.
Enabled	card.enabled	boolean	Whether enabled.
Exp Month	card.exp_month	integer	The expiration month of the associated card as an integer between 1 and 12.
Exp Year	card.exp_year	integer	The four-digit year of the card's expiration date.
Last 4	card.last_4	string	The last 4 digits of the card number.
Prepaid Type	card.prepaid_type	string	Indicates whether the Card is prepaid or not.
Reference ID	card.reference_id	string	An optional user-defined reference ID.
Version	card.version	integer	The current version of this object.

Create customer

Operation ID:

CustomerCreate

Creates a new customer for a business.

Parameters

Name	Key	Required	Type	Description
Given Name	given_name		string	The given name (that is, the first name) associated with the customer profile.
Family Name	family_name		string	The family name (that is, the last name) associated with the customer profile.
Email Address	email_address		string	The email address associated with the customer profile.
Company Name	company_name		string	A business name associated with the customer profile.
Nickname	nickname		string	A nickname for the customer profile.
Address Line 1	address_line_1		string	The first line of the address.
Address Line 2	address_line_2		string	The second line of the address, if any.
Locality	locality		string	The city or town of the address.
Administrative District Level 1	administrative_district_level_1		string	A civil entity within the address's country. In the US, this is the state.
Postal Code	postal_code		string	The address's postal code.
Country	country		string	The ISO 3166 Alpha-2 country code.
Phone Number	phone_number		string	The 11-digit phone number associated with the customer profile.
Reference ID	reference_id		string	An optional second ID used to associate the customer profile with an entity in another system.
Note	note		string	A custom note associated with the customer profile.
Birthday	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 and 1998-09-21T00:00:00-00:00 represents a birthday on September 21, 1998. You can also specify this value in YYYY-MM-DD format.

Returns

Name	Path	Type	Description
ID	customer.id	string	The unique, Square-issued identifier.
Created At	customer.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	customer.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Given Name	customer.given_name	string	The given (i.e., first) name associated with the customer profile.
Family Name	customer.family_name	string	The family (i.e., last) name associated with the customer profile.
Email Address	customer.email_address	string	The email address associated with the customer profile.
Company Name	customer.company_name	string	A business name associated with the customer profile.
Nickname	customer.nickname	string	A nickname for the customer profile.
Address Line 1	customer.address.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.
Address Line 2	customer.address.address_line_2	string	The second line of the address, if any.
Locality	customer.address.locality	string	The city or town of the address.
Administrative District Level 1	customer.address.administrative_district_level_1	string	A civil entity within the address's country. In the US, this is the state.
Postal Code	customer.address.postal_code	string	The address's postal code.
Country	customer.address.country	string	The address's country, in ISO 3166-1-alpha-2 format.
Phone Number	customer.phone_number	string	The 11-digit phone number associated with the customer profile.
Reference ID	customer.reference_id	string	An optional user-defined reference ID.
Note	customer.note	string	A custom note associated with the customer profile.
Birthday	customer.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 and 1998-09-21T00:00:00-00:00 represents a birthday on September 21, 1998.
Email Unsubscribed	customer.preferences.email_unsubscribed	boolean	Indicates whether the customer has unsubscribed from marketing campaign emails. A value of true means that the customer chose to opt out of email marketing from the current Square seller or from all Square sellers.
Creation Source	customer.creation_source	string	A creation source represents the method used to create the customer profile.
Version	customer.version	integer	The current version of this object.

Create customer group

Operation ID:

CustomGroupCreate

Creates a new customer group for a business.

Parameters

Name	Key	Required	Type	Description
Name	name		string	The name of the object.

Returns

Name	Path	Type	Description
ID	group.id	string	The unique, Square-issued identifier.
Name	group.name	string	The name of the object.
Created At	group.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	group.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.

Create dispute evidence text

Operation ID:

DisputeCreateEvidenceText

Uploads text to use as evidence for a dispute challenge.

Parameters

Name	Key	Required	Type	Description
Dispute ID	dispute_id	True	string	The identifier of the dispute.
Evidence Type	evidence_type		string	The type of evidence you are uploading.
Evidence Text	evidence_text		string	The evidence string.
Idempotency Key	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).

Returns

Name	Path	Type	Description
ID	evidence.id	string	The unique, Square-issued identifier.
Dispute ID	evidence.dispute_id	string	The ID of the dispute the evidence is associated with.
Evidence Text	evidence.evidence_text	string	The raw text.
Evidence Type	evidence.evidence_type	string	The type pf evidence.
Uploaded At	evidence.uploaded_at	string	The time when the next action is due, in RFC 3339 format.

Create invoice

Operation ID:

InvoiceCreate

Creates a draft invoice for an order created using the Orders API. A draft invoice remains in your account and no action is taken. You must publish the invoice before Square can process it (send it to the customer's email address or charge the customer’s card on file).

Parameters

Name	Key	Required	Type	Description
Idempotency Key	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).
Location ID	location_id		string	The identifier of the location.
Order ID	order_id		string	The ID of the order.
Scheduled At	scheduled_at		string	The timestamp when the processing is scheduled, in RFC 3339 format.
Customer ID	customer_id		string	The ID of the customer associated with the order.
Delivery Method	delivery_method		string	The delivery method that Square uses to send the invoice, reminders, and receipts to the customer. After the invoice is published, Square processes the invoice based on the delivery method and payment request settings, either immediately or on the scheduled_at date, if specified.
Request Type	request_type		string	Identifies the payment request type. This type defines how the payment request amount is determined.
Due Date	due_date		string	The due date for the payment request, in YYYY-MM-DD format.
Tipping Enabled	tipping_enabled		boolean	If set to true, provides a place for the customer to pay a tip.
Automatic Payment Source	automatic_payment_source		string	The payment method for an automatic payment.
Message	message		string	The message.
Relative Scheduled Days	relative_scheduled_days		integer	The number of days before (a negative number) or after (a positive number) the payment request due_date when the reminder is sent.
Invoice Number	invoice_number		string	A user-friendly invoice number. The value is unique within a location. If not provided when creating an invoice, Square assigns a value.
Title	title		string	The title.
Description	description		string	The description.
Card	card		boolean	Indicates whether credit card or debit card payments are accepted.
Square Gift Card	square_gift_card		boolean	Indicates whether Square gift card payments are accepted.
Bank Account	bank_account		boolean	Indicates whether bank transfer payments are accepted.
Label	label		string	The label or title of the custom field.
Value	value		string	The text of the custom field.
Placement	placement		string	The location of the custom field on the invoice.
Sale or Service Date	sale_or_service_date		string	The date of the sale or the date that the service is rendered, in YYYY-MM-DD format. This field can be used to specify a past or future date which is displayed on the invoice.

Returns

Name	Path	Type	Description
ID	invoice.id	string	The unique, Square-issued identifier.
Version	invoice.version	integer	The current version of this object.
Location ID	invoice.location_id	string	The identifier of the location.
Order ID	invoice.order_id	string	The ID of the order.
Payment Requests	invoice.payment_requests	array of object
UID	invoice.payment_requests.uid	string	The Square-generated ID.
Request Type	invoice.payment_requests.request_type	string	Identifies the payment request type. This type defines how the payment request amount is determined.
Due Date	invoice.payment_requests.due_date	string	The due date for the payment request, in YYYY-MM-DD format.
Tipping Enabled	invoice.payment_requests.tipping_enabled	boolean	If set to true, provides a place for the customer to pay a tip.
Reminders	invoice.payment_requests.reminders	array of object
UID	invoice.payment_requests.reminders.uid	string	A Square-assigned ID.
Relative Scheduled Days	invoice.payment_requests.reminders.relative_scheduled_days	integer	The number of days before (a negative number) or after (a positive number) the payment request due_date when the reminder is sent.
Message	invoice.payment_requests.reminders.message	string	The message.
Status	invoice.payment_requests.reminders.status	string	The current status.
Amount	invoice.payment_requests.computed_amount_money.amount	integer	The amount.
Currency	invoice.payment_requests.computed_amount_money.currency	string	The currency.
Amount	invoice.payment_requests.total_completed_amount_money.amount	integer	The amount.
Currency	invoice.payment_requests.total_completed_amount_money.currency	string	The currency.
Automatic Payment Source	invoice.payment_requests.automatic_payment_source	string	The payment method for an automatic payment.
Invoice Number	invoice.invoice_number	string	A user-friendly invoice number. The value is unique within a location. If not provided when creating an invoice, Square assigns a value.
Title	invoice.title	string	The title.
Description	invoice.description	string	The description.
Scheduled At	invoice.scheduled_at	string	The timestamp when the processing is scheduled, in RFC 3339 format.
Status	invoice.status	string	The current verification status of this object.
Timezone	invoice.timezone	string	The time zone used to interpret calendar dates. When an invoice is created, this field is set to the timezone specified for the seller location. The value cannot be changed.
Created At	invoice.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	invoice.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Customer ID	invoice.primary_recipient.customer_id	string	The ID of the customer associated with the order.
Given Name	invoice.primary_recipient.given_name	string	The recipient's given (that is, first) name.
Family Name	invoice.primary_recipient.family_name	string	The recipient's family (that is, last) name.
Email Address	invoice.primary_recipient.email_address	string	The recipient's email address.
Phone Number	invoice.primary_recipient.phone_number	string	The recipient's phone number.
Card	invoice.accepted_payment_methods.card	boolean	Indicates whether credit card or debit card payments are accepted.
Square Gift Card	invoice.accepted_payment_methods.square_gift_card	boolean	Indicates whether Square gift card payments are accepted.
Bank Account	invoice.accepted_payment_methods.bank_account	boolean	Indicates whether bank transfer payments are accepted.
Custom Fields	invoice.custom_fields	array of object
Label	invoice.custom_fields.label	string	The label or title of the custom field.
Value	invoice.custom_fields.value	string	The text of the custom field.
Placement	invoice.custom_fields.placement	string	The location of the custom field on the invoice.
Delivery Method	invoice.delivery_method	string	The delivery method that Square uses to send the invoice, reminders, and receipts to the customer. After the invoice is published, Square processes the invoice based on the delivery method and payment request settings, either immediately or on the scheduled_at date, if specified.
Sale or Service Date	invoice.sale_or_service_date	string	The date of the sale or the date that the service is rendered, in YYYY-MM-DD format. This field can be used to specify a past or future date which is displayed on the invoice.

Create order

Operation ID:

OrderCreate

Creates a new order that can include information about products for purchase and settings to apply to the purchase.

Parameters

Name	Key	Required	Type	Description
Idempotency Key	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).
Reference ID	reference_id		string	An optional user-defined reference ID.
Location ID	location_id		string	The identifier of the location.
Name	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.
Quantity	quantity		string	The number of items affected by the physical count as a decimal string. The number can support up to 5 digits after the decimal point.
Amount	amount		integer	The amount.
Currency	currency		string	The currency.
Catalog Object ID	catalog_object_id		string	The Square-generated ID of the CatalogObject being tracked.
Catalog Object ID	catalog_object_id		string	The catalog object ID.
Discount UID	discount_uid		string	The uid of the discount that the applied discount represents.
UID	uid		string	The Square-generated ID.
Name	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.
Percentage	percentage		string	The percentage in decimal form, using a '.' as the decimal separator and without a '%' sign. A value of 7.5 corresponds to 7.5%.
Scope	scope		string	Indicates the current level.
UID	uid		string	The Square-generated ID.
Name	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.
Percentage	percentage		string	The percentage in decimal form, using a '.' as the decimal separator and without a '%' sign. A value of 7.5 corresponds to 7.5%.
Scope	scope		string	Indicates the current level.
Catalog Object ID	catalog_object_id		string	The Square-generated ID of the CatalogObject being tracked.
Amount	amount		integer	The amount.
Currency	currency		string	The currency.

Returns

Name	Path	Type	Description
ID	order.id	string	The unique, Square-issued identifier.
Location ID	order.location_id	string	The identifier of the location.
Line Items	order.line_items	array of object
UID	order.line_items.uid	string	The Square-generated ID.
Name	order.line_items.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.
Quantity	order.line_items.quantity	string	The number of items affected by the physical count as a decimal string. The number can support up to 5 digits after the decimal point.
Applied Taxes	order.line_items.applied_taxes	array of object
UID	order.line_items.applied_taxes.uid	string	A Square-assigned ID.
Tax UID	order.line_items.applied_taxes.tax_uid	string	The UID of the tax for which this applied tax represents.
Amount	order.line_items.applied_taxes.applied_money.amount	integer	The amount.
Currency	order.line_items.applied_taxes.applied_money.currency	string	The currency.
Applied Discounts	order.line_items.applied_discounts	array of object
UID	order.line_items.applied_discounts.uid	string	A Square-assigned ID.
Discount UID	order.line_items.applied_discounts.discount_uid	string	The uid of the discount that the applied discount represents.
Amount	order.line_items.applied_discounts.applied_money.amount	integer	The amount.
Currency	order.line_items.applied_discounts.applied_money.currency	string	The currency.
Amount	order.line_items.base_price_money.amount	integer	The amount.
Currency	order.line_items.base_price_money.currency	string	The currency.
Amount	order.line_items.gross_sales_money.amount	integer	The amount.
Currency	order.line_items.gross_sales_money.currency	string	The currency.
Amount	order.line_items.total_tax_money.amount	integer	The amount.
Currency	order.line_items.total_tax_money.currency	string	The currency.
Amount	order.line_items.total_discount_money.amount	integer	The amount.
Currency	order.line_items.total_discount_money.currency	string	The currency.
Amount	order.line_items.total_money.amount	integer	The amount.
Currency	order.line_items.total_money.currency	string	The currency.
Amount	order.line_items.variation_total_price_money.amount	integer	The amount.
Currency	order.line_items.variation_total_price_money.currency	string	The currency.
Catalog Object ID	order.line_items.catalog_object_id	string	The Square-generated ID of the CatalogObject being tracked.
Variation Name	order.line_items.variation_name	string	The name of the variation applied to this line item.
Modifiers	order.line_items.modifiers	array of object
UID	order.line_items.modifiers.uid	string	A Square-assigned ID.
Catalog Object ID	order.line_items.modifiers.catalog_object_id	string	The catalog object ID.
Name	order.line_items.modifiers.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.
Amount	order.line_items.modifiers.base_price_money.amount	integer	The amount.
Currency	order.line_items.modifiers.base_price_money.currency	string	The currency.
Amount	order.line_items.modifiers.total_price_money.amount	integer	The amount.
Currency	order.line_items.modifiers.total_price_money.currency	string	The currency.
Taxes	order.taxes	array of object
UID	order.taxes.uid	string	The Square-generated ID.
Name	order.taxes.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.
Type	order.taxes.type	string	Indicates the type.
Percentage	order.taxes.percentage	string	The percentage in decimal form, using a '.' as the decimal separator and without a '%' sign. A value of 7.5 corresponds to 7.5%.
Amount	order.taxes.applied_money.amount	integer	The amount.
Currency	order.taxes.applied_money.currency	string	The currency.
Scope	order.taxes.scope	string	Indicates the current level.
Discounts	order.discounts	array of object
UID	order.discounts.uid	string	The Square-generated ID.
Catalog Object ID	order.discounts.catalog_object_id	string	The Square-generated ID of the CatalogObject being tracked.
Name	order.discounts.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.
Type	order.discounts.type	string	Indicates the type.
Percentage	order.discounts.percentage	string	The percentage in decimal form, using a '.' as the decimal separator and without a '%' sign. A value of 7.5 corresponds to 7.5%.
Amount	order.discounts.applied_money.amount	integer	The amount.
Currency	order.discounts.applied_money.currency	string	The currency.
Scope	order.discounts.scope	string	Indicates the current level.
Amount	order.discounts.amount_money.amount	integer	The amount.
Currency	order.discounts.amount_money.currency	string	The currency.
Created At	order.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	order.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
State	order.state	string	The current state.
Version	order.version	integer	The current version of this object.
Reference ID	order.reference_id	string	An optional user-defined reference ID.
Amount	order.total_money.amount	integer	The amount.
Currency	order.total_money.currency	string	The currency.
Amount	order.total_tax_money.amount	integer	The amount.
Currency	order.total_tax_money.currency	string	The currency.
Amount	order.total_discount_money.amount	integer	The amount.
Currency	order.total_discount_money.currency	string	The currency.
Amount	order.total_tip_money.amount	integer	The amount.
Currency	order.total_tip_money.currency	string	The currency.
Amount	order.total_service_charge_money.amount	integer	The amount.
Currency	order.total_service_charge_money.currency	string	The currency.
Amount	order.net_amounts.total_money.amount	integer	The amount.
Currency	order.net_amounts.total_money.currency	string	The currency.
Amount	order.net_amounts.tax_money.amount	integer	The amount.
Currency	order.net_amounts.tax_money.currency	string	The currency.
Amount	order.net_amounts.discount_money.amount	integer	The amount.
Currency	order.net_amounts.discount_money.currency	string	The currency.
Amount	order.net_amounts.tip_money.amount	integer	The amount.
Currency	order.net_amounts.tip_money.currency	string	The currency.
Amount	order.net_amounts.service_charge_money.amount	integer	The amount.
Currency	order.net_amounts.service_charge_money.currency	string	The currency.
Name	order.source.name	string	The name.

Create payment

Operation ID:

PaymentCreate

Creates a payment using the provided source. You can use this endpoint to charge a card (credit/debit card or Square gift card) or record a payment that the seller received outside of Square (cash payment from a buyer or a payment that an external entity processed on behalf of the seller).

Parameters

Name	Key	Required	Type	Description
Idempotency Key	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).
Amount	amount		integer	The amount of money to accept for this payment, not including tip_money.
Currency	currency		string	The 3-character ISO 4217 currency code.
Source ID	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.
Autocomplete	autocomplete		boolean	If set to true, this payment will be completed when possible. If set to false, this payment is held in an approved state until either explicitly completed (captured) or canceled (voided).
Customer ID	customer_id		string	The ID of the customer to be linked.
Location ID	location_id		string	The location identifier.
Reference ID	reference_id		string	An optional second ID used to associate the customer profile with an entity in another system.
Note	note		string	A custom note associated with the customer profile.
Amount	amount		integer	The amount of money to accept for this payment, not including tip_money.
Currency	currency		string	The 3-character ISO 4217 currency code.

Returns

Name	Path	Type	Description
ID	payment.id	string	The unique, Square-issued identifier.
Created At	payment.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	payment.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Amount	payment.amount_money.amount	integer	The amount.
Currency	payment.amount_money.currency	string	The currency.
Amount	payment.app_fee_money.amount	integer	The amount.
Currency	payment.app_fee_money.currency	string	The currency.
Status	payment.status	string	The current verification status of this object.
Delay Duration	payment.delay_duration	string	The duration of time after the payment's creation when Square automatically applies the delay_action to the payment. This automatic delay_action applies only to payments that do not reach a terminal state (COMPLETED, CANCELED, or FAILED) before the delay_duration time period. This field is specified as a time duration, in RFC 3339 format.
Source Type	payment.source_type	string	The source type for this payment. Current values include CARD, BANK_ACCOUNT, WALLET, CASH, or EXTERNAL.
Status	payment.card_details.status	string	The current status.
Card Brand	payment.card_details.card.card_brand	string	The card's brand.
Last 4	payment.card_details.card.last_4	string	The last 4 digits of the card number.
Exp Month	payment.card_details.card.exp_month	integer	The expiration month of the associated card as an integer between 1 and 12.
Exp Year	payment.card_details.card.exp_year	integer	The four-digit year of the card's expiration date.
Fingerprint	payment.card_details.card.fingerprint	string	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
Card Type	payment.card_details.card.card_type	string	The type of the card.
Prepaid Type	payment.card_details.card.prepaid_type	string	Indicates whether the Card is prepaid or not.
BIN	payment.card_details.card.bin	string	The first six digits of the card number, known as the Bank Identification Number (BIN).
Entry Method	payment.card_details.entry_method	string	The method used to enter the card's details for the payment. The method can be KEYED, SWIPED, EMV, ON_FILE, or CONTACTLESS.
CVV Status	payment.card_details.cvv_status	string	The status code returned from the Card Verification Value (CVV) check. The code can be CVV_ACCEPTED, CVV_REJECTED, or CVV_NOT_CHECKED.
AVS Status	payment.card_details.avs_status	string	The status code returned from the Address Verification System (AVS) check. The code can be AVS_ACCEPTED, AVS_REJECTED, or AVS_NOT_CHECKED.
Auth Result Code	payment.card_details.auth_result_code	string	The status code returned by the card issuer that describes the payment's authorization status.
Statement Description	payment.card_details.statement_description	string	The statement description sent to the card networks.
Authorized At	payment.card_details.card_payment_timeline.authorized_at	string	The timestamp when the payment was authorized, in RFC 3339 format.
Captured At	payment.card_details.card_payment_timeline.captured_at	string	The timestamp when the payment was captured, in RFC 3339 format.
Location ID	payment.location_id	string	The identifier of the location.
Order ID	payment.order_id	string	The ID of the order.
Reference ID	payment.reference_id	string	An optional user-defined reference ID.
Created At	payment.risk_evaluation.created_at	string	The timestamp when created, in RFC 3339 format.
Risk Level	payment.risk_evaluation.risk_level	string	The risk level associated with the payment.
Note	payment.note	string	A custom note associated with the customer profile.
Customer ID	payment.customer_id	string	The ID of this object representing the customer.
Amount	payment.total_money.amount	integer	The amount.
Currency	payment.total_money.currency	string	The currency.
Amount	payment.approved_money.amount	integer	The amount.
Currency	payment.approved_money.currency	string	The currency.
Receipt Number	payment.receipt_number	string	The payment's receipt number. The field is missing if a payment is canceled.
Receipt URL	payment.receipt_url	string	The URL for the payment's receipt. The field is only populated for COMPLETED payments.
Delay Action	payment.delay_action	string	The action to be applied to the payment when the delay_duration has elapsed.
Delayed Until	payment.delayed_until	string	The read-only timestamp of when the delay_action is automatically applied, in RFC 3339 format.
Square Product	payment.application_details.square_product	string	The Square product, such as Square Point of Sale (POS), Square Invoices, or Square Virtual Terminal.
Application ID	payment.application_details.application_id	string	Read-only Square ID assigned to the application.
Version Token	payment.version_token	string	This opaque token identifies a specific version of the object.

Create subscription

Operation ID:

SubscriptionCreate

Creates a subscription for a customer to a subscription plan. If you provide a card on file in the request, Square charges the card for the subscription. Otherwise, Square bills an invoice to the customer's email address. The subscription starts immediately, unless the request includes the optional start_date. Each individual subscription is associated with a particular location.

Parameters

Name	Key	Required	Type	Description
Idempotency Key	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).
Location ID	location_id		string	The location identifier.
Plan ID	plan_id		string	The ID of the subscription plan created using the Catalog API.
Customer ID	customer_id		string	The ID of the customer to be linked.
Card ID	card_id		string	The ID of the customer card to charge.
Start Date	start_date		string	The start date of the subscription, in YYYY-MM-DD format.
Tax Percentage	tax_percentage		string	The tax to add when billing the subscription.
Amount	amount		integer	The amount of money to accept for this payment, not including tip_money.
Currency	currency		string	The 3-character ISO 4217 currency code.
Timezone	timezone		string	The timezone that is used in date calculations for the subscription.
Name	name		string	The name of the object.

Returns

Name	Path	Type	Description
ID	subscription.id	string	The unique, Square-issued identifier.
Location ID	subscription.location_id	string	The identifier of the location.
Plan ID	subscription.plan_id	string	The ID of the associated subscription plan.
Customer ID	subscription.customer_id	string	The ID of this object representing the customer.
Start Date	subscription.start_date	string	The start date of the subscription, in YYYY-MM-DD format.
Status	subscription.status	string	The current verification status of this object.
Tax Percentage	subscription.tax_percentage	string	The tax amount applied when billing the subscription.
Amount	subscription.price_override_money.amount	integer	The amount.
Currency	subscription.price_override_money.currency	string	The currency.
Version	subscription.version	integer	The current version of this object.
Created At	subscription.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Card ID	subscription.card_id	string	The ID of the customer card that is charged for the subscription.
Timezone	subscription.timezone	string	The time zone used to interpret calendar dates. When an invoice is created, this field is set to the timezone specified for the seller location. The value cannot be changed.
Name	subscription.source.name	string	The name.

Create terminal checkout

Operation ID:

TerminalCreateCheckout

Creates a Terminal checkout request and sends it to the specified device to take a payment for the requested amount.

Parameters

Name	Key	Required	Type	Description
Idempotency Key	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).
Amount	amount		integer	The amount.
Currency	currency		string	The currency.
Reference ID	reference_id		string	An optional user-defined reference ID.
Device ID	device_id		string	The unique ID of the device intended for this TerminalCheckout.
Note	note		string	A custom note associated with the customer profile.

Returns

Name	Path	Type	Description
ID	checkout.id	string	The unique, Square-issued identifier.
Amount	checkout.amount_money.amount	integer	The amount.
Currency	checkout.amount_money.currency	string	The currency.
Reference ID	checkout.reference_id	string	An optional user-defined reference ID.
Note	checkout.note	string	A custom note associated with the customer profile.
Device ID	checkout.device_options.device_id	string	The unique ID of the device intended for this TerminalCheckout.
Allow Tipping	checkout.device_options.tip_settings.allow_tipping	boolean	Indicates whether tipping is enabled for this checkout. Defaults to false.
Skip Receipt Screen	checkout.device_options.skip_receipt_screen	boolean	Instructs the device to skip the receipt screen. Defaults to false.
Status	checkout.status	string	The current verification status of this object.
Created At	checkout.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	checkout.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
App ID	checkout.app_id	string	The ID of the application that created the checkout.
Deadline Duration	checkout.deadline_duration	string	An RFC 3339 duration, after which the checkout is automatically canceled. A TerminalCheckout that is PENDING is automatically CANCELED and has a cancellation reason of TIMED_OUT. Default: 5 minutes from creation
Payment Type	checkout.payment_type	string	The type of payment the terminal should attempt to capture from. Defaults to CARD_PRESENT.

Create terminal refund

Operation ID:

TerminalCreateRefund

Creates a request to refund an Interac payment completed on a Square Terminal.

Parameters

Name	Key	Required	Type	Description
Idempotency Key	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).
Amount	amount		integer	The amount.
Currency	currency		string	The currency.
Device ID	device_id		string	The unique ID of the device intended for this TerminalRefund.
Reason	reason		string	The reason for this object.
Payment ID	payment_id		string	The unique ID of the payment.

Returns

Name	Path	Type	Description
ID	refund.id	string	The unique, Square-issued identifier.
Payment ID	refund.payment_id	string	The unique ID of the payment.
Amount	refund.amount_money.amount	integer	The amount.
Currency	refund.amount_money.currency	string	The currency.
Reason	refund.reason	string	The reason for this object.
Device ID	refund.device_id	string	The unique ID of the device intended for this TerminalRefund.
Deadline Duration	refund.deadline_duration	string	An RFC 3339 duration, after which the checkout is automatically canceled. A TerminalCheckout that is PENDING is automatically CANCELED and has a cancellation reason of TIMED_OUT. Default: 5 minutes from creation
Status	refund.status	string	The current verification status of this object.
Created At	refund.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	refund.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
App ID	refund.app_id	string	The ID of the application that created the checkout.
Card Brand	refund.card.card_brand	string	The brand of the card.
last_4	refund.card.last_4	string	The last 4 digits of the card number.
Exp Month	refund.card.exp_month	integer	The expiration month of the associated card as an integer between 1 and 12.
Exp Year	refund.card.exp_year	integer	The four-digit year of the card's expiration date.
Fingerprint	refund.card.fingerprint	string	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
Card Type	refund.card.card_type	string	The type of the card.
BIN	refund.card.bin	string	The first six digits of the card number, known as the Bank Identification Number (BIN).
Order ID	refund.order_id	string	The ID of the order.
Location ID	refund.location_id	string	The identifier of the location.

Delete catalog object

Operation ID:

CatalogDelete

Deletes a single CatalogObject based on the provided ID and returns the set of successfully deleted IDs in the response. Deletion is a cascading event such that all children of the targeted object are also deleted. For example, deleting a CatalogItem will also delete all of its CatalogItemVariation children.

Parameters

Name	Key	Required	Type	Description
Object ID	object_id	True	string	The identifier of the object.

Returns

Name	Path	Type	Description
Deleted Object IDs	deleted_object_ids	array of string
Deleted At	deleted_at	string	The database timestamp of this deletion in RFC 3339 format

Delete customer

Operation ID:

CustomerDelete

Deletes a customer profile from a business. This operation also unlinks any associated cards on file.

Parameters

Name	Key	Required	Type	Description
Customer ID	customer_id	True	string	The identifier of the customer.

Returns

response

object

Delete customer group

Operation ID:

CustomerGroupDelete

Deletes a customer group as identified by the group_id value.

Parameters

Name	Key	Required	Type	Description
Group ID	group_id	True	string	The identifier of the group.

Returns

response

object

Delete dispute evidence

Operation ID:

DisputeDeleteEvidence

Removes specified evidence from a dispute.

Parameters

Name	Key	Required	Type	Description
Dispute ID	dispute_id	True	string	The identifier of the dispute.
Evidence ID	evidence_id	True	string	The identifier of the evidence.

Returns

response

object

Delete invoice

Operation ID:

InvoiceDelete

Deletes the specified invoice. When an invoice is deleted, the associated order status changes to CANCELED. You can only delete a draft invoice (you cannot delete a published invoice, including one that is scheduled for processing).

Parameters

Name	Key	Required	Type	Description
Invoice ID	invoice_id	True	string	The identifier of the invoice.
Version	version		integer	The version of the invoice to delete.

Returns

response

object

Disable card

Operation ID:

CardDisable

Disables the card, preventing any further updates or charges. Disabling an already disabled card is allowed but has no effect.

Parameters

Name	Key	Required	Type	Description
Card ID	card_id	True	string	The identifier of the card.

Returns

Name	Path	Type	Description
ID	card.id	string	The unique, Square-issued identifier.
Address Line 1	card.billing_address.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.
Address Line 2	card.billing_address.address_line_2	string	The second line of the address, if any.
Locality	card.billing_address.locality	string	The city or town of the address.
Administrative District Level 1	card.billing_address.administrative_district_level_1	string	A civil entity within the address's country. In the US, this is the state.
Postal Code	card.billing_address.postal_code	string	The address's postal code.
Country	card.billing_address.country	string	The address's country, in ISO 3166-1-alpha-2 format.
Fingerprint	card.fingerprint	string	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
BIN	card.bin	string	The first six digits of the card number, known as the Bank Identification Number (BIN).
Card Brand	card.card_brand	string	The card's brand.
Card Type	card.card_type	string	The type of the card.
Cardholder Name	card.cardholder_name	string	The name of the cardholder.
Customer ID	card.customer_id	string	The ID of this object representing the customer.
Enabled	card.enabled	boolean	Whether enabled.
Exp Month	card.exp_month	integer	The expiration month of the associated card as an integer between 1 and 12.
Exp Year	card.exp_year	integer	The four-digit year of the card's expiration date.
Last 4	card.last_4	string	The last 4 digits of the card number.
Prepaid Type	card.prepaid_type	string	Indicates whether the Card is prepaid or not.
Reference ID	card.reference_id	string	An optional user-defined reference ID.
Version	card.version	integer	The current version of this object.

Get invoice

Operation ID:

InvoiceGet

Retrieves an invoice by invoice ID.

Parameters

Name	Key	Required	Type	Description
Invoice ID	invoice_id	True	string	The identifier of the invoice.

Returns

Name	Path	Type	Description
ID	invoice.id	string	The unique, Square-issued identifier.
Version	invoice.version	integer	The current version of this object.
Location ID	invoice.location_id	string	The identifier of the location.
Order ID	invoice.order_id	string	The ID of the order.
Payment Requests	invoice.payment_requests	array of object
UID	invoice.payment_requests.uid	string	The Square-generated ID.
Request Type	invoice.payment_requests.request_type	string	Identifies the payment request type. This type defines how the payment request amount is determined.
Due Date	invoice.payment_requests.due_date	string	The due date for the payment request, in YYYY-MM-DD format.
Tipping Enabled	invoice.payment_requests.tipping_enabled	boolean	If set to true, provides a place for the customer to pay a tip.
Reminders	invoice.payment_requests.reminders	array of object
UID	invoice.payment_requests.reminders.uid	string	A Square-assigned ID.
Relative Scheduled Days	invoice.payment_requests.reminders.relative_scheduled_days	integer	The number of days before (a negative number) or after (a positive number) the payment request due_date when the reminder is sent.
Message	invoice.payment_requests.reminders.message	string	The message.
Status	invoice.payment_requests.reminders.status	string	The current status.
Amount	invoice.payment_requests.computed_amount_money.amount	integer	The amount.
Currency	invoice.payment_requests.computed_amount_money.currency	string	The currency.
Amount	invoice.payment_requests.total_completed_amount_money.amount	integer	The amount.
Currency	invoice.payment_requests.total_completed_amount_money.currency	string	The currency.
Automatic Payment Source	invoice.payment_requests.automatic_payment_source	string	The payment method for an automatic payment.
Invoice Number	invoice.invoice_number	string	A user-friendly invoice number. The value is unique within a location. If not provided when creating an invoice, Square assigns a value.
Title	invoice.title	string	The title.
Description	invoice.description	string	The description.
Scheduled At	invoice.scheduled_at	string	The timestamp when the processing is scheduled, in RFC 3339 format.
Status	invoice.status	string	The current verification status of this object.
Timezone	invoice.timezone	string	The time zone used to interpret calendar dates. When an invoice is created, this field is set to the timezone specified for the seller location. The value cannot be changed.
Created At	invoice.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	invoice.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Customer ID	invoice.primary_recipient.customer_id	string	The ID of the customer associated with the order.
Given Name	invoice.primary_recipient.given_name	string	The recipient's given (that is, first) name.
Family Name	invoice.primary_recipient.family_name	string	The recipient's family (that is, last) name.
Email Address	invoice.primary_recipient.email_address	string	The recipient's email address.
Phone Number	invoice.primary_recipient.phone_number	string	The recipient's phone number.
Card	invoice.accepted_payment_methods.card	boolean	Indicates whether credit card or debit card payments are accepted.
Square Gift Card	invoice.accepted_payment_methods.square_gift_card	boolean	Indicates whether Square gift card payments are accepted.
Bank Account	invoice.accepted_payment_methods.bank_account	boolean	Indicates whether bank transfer payments are accepted.
Custom Fields	invoice.custom_fields	array of object
Label	invoice.custom_fields.label	string	The label or title of the custom field.
Value	invoice.custom_fields.value	string	The text of the custom field.
Placement	invoice.custom_fields.placement	string	The location of the custom field on the invoice.
Delivery Method	invoice.delivery_method	string	The delivery method that Square uses to send the invoice, reminders, and receipts to the customer. After the invoice is published, Square processes the invoice based on the delivery method and payment request settings, either immediately or on the scheduled_at date, if specified.
Sale or Service Date	invoice.sale_or_service_date	string	The date of the sale or the date that the service is rendered, in YYYY-MM-DD format. This field can be used to specify a past or future date which is displayed on the invoice.

Get payment

Operation ID:

PaymentGet

Retrieves details for a specific payment.

Parameters

Name	Key	Required	Type	Description
Payment ID	payment_id	True	string	The identifier of the payment.

Returns

Name	Path	Type	Description
ID	payment.id	string	The unique, Square-issued identifier.
Created At	payment.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	payment.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Amount	payment.amount_money.amount	integer	The amount.
Currency	payment.amount_money.currency	string	The currency.
Status	payment.status	string	The current verification status of this object.
Delay Duration	payment.delay_duration	string	The duration of time after the payment's creation when Square automatically applies the delay_action to the payment. This automatic delay_action applies only to payments that do not reach a terminal state (COMPLETED, CANCELED, or FAILED) before the delay_duration time period. This field is specified as a time duration, in RFC 3339 format.
Source Type	payment.source_type	string	The source type for this payment. Current values include CARD, BANK_ACCOUNT, WALLET, CASH, or EXTERNAL.
Status	payment.card_details.status	string	The current status.
Card Brand	payment.card_details.card.card_brand	string	The card's brand.
Last 4	payment.card_details.card.last_4	string	The last 4 digits of the card number.
Exp Month	payment.card_details.card.exp_month	integer	The expiration month of the associated card as an integer between 1 and 12.
Exp Year	payment.card_details.card.exp_year	integer	The four-digit year of the card's expiration date.
Fingerprint	payment.card_details.card.fingerprint	string	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
Card Type	payment.card_details.card.card_type	string	The type of the card.
Prepaid Type	payment.card_details.card.prepaid_type	string	Indicates whether the Card is prepaid or not.
BIN	payment.card_details.card.bin	string	The first six digits of the card number, known as the Bank Identification Number (BIN).
Entry Method	payment.card_details.entry_method	string	The method used to enter the card's details for the payment. The method can be KEYED, SWIPED, EMV, ON_FILE, or CONTACTLESS.
CVV Status	payment.card_details.cvv_status	string	The status code returned from the Card Verification Value (CVV) check. The code can be CVV_ACCEPTED, CVV_REJECTED, or CVV_NOT_CHECKED.
AVS Status	payment.card_details.avs_status	string	The status code returned from the Address Verification System (AVS) check. The code can be AVS_ACCEPTED, AVS_REJECTED, or AVS_NOT_CHECKED.
Auth Result Code	payment.card_details.auth_result_code	string	The status code returned by the card issuer that describes the payment's authorization status.
Statement Description	payment.card_details.statement_description	string	The statement description sent to the card networks.
Authorized At	payment.card_details.card_payment_timeline.authorized_at	string	The timestamp when the payment was authorized, in RFC 3339 format.
Captured At	payment.card_details.card_payment_timeline.captured_at	string	The timestamp when the payment was captured, in RFC 3339 format.
Location ID	payment.location_id	string	The identifier of the location.
Order ID	payment.order_id	string	The ID of the order.
Processing Fee	payment.processing_fee	array of object
Effective At	payment.processing_fee.effective_at	string	The timestamp of when the fee takes effect, in RFC 3339 format.
Type	payment.processing_fee.type	string	Indicates the type.
Amount	payment.processing_fee.amount_money.amount	integer	The amount.
Currency	payment.processing_fee.amount_money.currency	string	The currency.
Note	payment.note	string	A custom note associated with the customer profile.
Amount	payment.total_money.amount	integer	The amount.
Currency	payment.total_money.currency	string	The currency.
Amount	payment.approved_money.amount	integer	The amount.
Currency	payment.approved_money.currency	string	The currency.
Employee ID	payment.employee_id	string	The Square-generated ID of the Employee.
Receipt Number	payment.receipt_number	string	The payment's receipt number. The field is missing if a payment is canceled.
Receipt URL	payment.receipt_url	string	The URL for the payment's receipt. The field is only populated for COMPLETED payments.
Delay Action	payment.delay_action	string	The action to be applied to the payment when the delay_duration has elapsed.
Delayed Until	payment.delayed_until	string	The read-only timestamp of when the delay_action is automatically applied, in RFC 3339 format.
Team Member ID	payment.team_member_id	string	The ID of the team member.
Square Product	payment.application_details.square_product	string	The Square product, such as Square Point of Sale (POS), Square Invoices, or Square Virtual Terminal.
Application ID	payment.application_details.application_id	string	Read-only Square ID assigned to the application.
Version Token	payment.version_token	string	This opaque token identifies a specific version of the object.

Get payment refund

Operation ID:

RefundGet

Retrieves a specific refund using the refund_id.

Parameters

Name	Key	Required	Type	Description
Refund ID	refund_id	True	string	The identifier of the refund.

Returns

Name	Path	Type	Description
ID	refund.id	string	The unique, Square-issued identifier.
Status	refund.status	string	The current verification status of this object.
Amount	refund.amount_money.amount	integer	The amount.
Currency	refund.amount_money.currency	string	The currency.
Payment ID	refund.payment_id	string	The unique ID of the payment.
Order ID	refund.order_id	string	The ID of the order.
Created At	refund.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	refund.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Processing Fee	refund.processing_fee	array of object
Effective At	refund.processing_fee.effective_at	string	The timestamp of when the fee takes effect, in RFC 3339 format.
Type	refund.processing_fee.type	string	Indicates the type.
Amount	refund.processing_fee.amount_money.amount	integer	The amount.
Currency	refund.processing_fee.amount_money.currency	string	The currency.
Location ID	refund.location_id	string	The identifier of the location.
Reason	refund.reason	string	The reason for this object.

Get terminal checkout

Operation ID:

TerminalGetCheckout

Retrieves a Terminal checkout request by checkout_id.

Parameters

Name	Key	Required	Type	Description
Checkout ID	checkout_id	True	string	The identifier of the checkout.

Returns

Name	Path	Type	Description
ID	checkout.id	string	The unique, Square-issued identifier.
Amount	checkout.amount_money.amount	integer	The amount.
Currency	checkout.amount_money.currency	string	The currency.
Reference ID	checkout.reference_id	string	An optional user-defined reference ID.
Note	checkout.note	string	A custom note associated with the customer profile.
Device ID	checkout.device_options.device_id	string	The unique ID of the device intended for this TerminalCheckout.
Allow Tipping	checkout.device_options.tip_settings.allow_tipping	boolean	Indicates whether tipping is enabled for this checkout. Defaults to false.
Skip Receipt Screen	checkout.device_options.skip_receipt_screen	boolean	Instructs the device to skip the receipt screen. Defaults to false.
Status	checkout.status	string	The current verification status of this object.
Created At	checkout.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	checkout.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
App ID	checkout.app_id	string	The ID of the application that created the checkout.
Deadline Duration	checkout.deadline_duration	string	An RFC 3339 duration, after which the checkout is automatically canceled. A TerminalCheckout that is PENDING is automatically CANCELED and has a cancellation reason of TIMED_OUT. Default: 5 minutes from creation

Get terminal refund

Operation ID:

TerminalGetRefund

Retrieves an Interac Terminal refund object by ID.

Parameters

Name	Key	Required	Type	Description
Terminal Refund ID	terminal_refund_id	True	string	The identifier of the terminal refund.

Returns

Name	Path	Type	Description
ID	refund.id	string	The unique, Square-issued identifier.
Refund ID	refund.refund_id	string	The unique ID for this refund, generated by Square.
Payment ID	refund.payment_id	string	The unique ID of the payment.
Amount	refund.amount_money.amount	integer	The amount.
Currency	refund.amount_money.currency	string	The currency.
Reason	refund.reason	string	The reason for this object.
Device ID	refund.device_id	string	The unique ID of the device intended for this TerminalRefund.
Deadline Duration	refund.deadline_duration	string	An RFC 3339 duration, after which the checkout is automatically canceled. A TerminalCheckout that is PENDING is automatically CANCELED and has a cancellation reason of TIMED_OUT. Default: 5 minutes from creation
Status	refund.status	string	The current verification status of this object.
Created At	refund.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	refund.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
App ID	refund.app_id	string	The ID of the application that created the checkout.
Card Brand	refund.card.card_brand	string	The brand of the card.
last_4	refund.card.last_4	string	The last 4 digits of the card number.
Exp Month	refund.card.exp_month	integer	The expiration month of the associated card as an integer between 1 and 12.
Exp Year	refund.card.exp_year	integer	The four-digit year of the card's expiration date.
Fingerprint	refund.card.fingerprint	string	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
Card Type	refund.card.card_type	string	The type of the card.
BIN	refund.card.bin	string	The first six digits of the card number, known as the Bank Identification Number (BIN).
Order ID	refund.order_id	string	The ID of the order.
Location ID	refund.location_id	string	The identifier of the location.

List cards

Operation ID:

CardList

Retrieves a list of cards owned by the account making the request.

Parameters

Name	Key	Required	Type	Description
Cursor	cursor		string	The pagination cursor returned by a previous call to this endpoint.
Customer ID	customer_id		string	Limit results to cards associated with the customer supplied. By default, all cards owned by the merchant are returned.
Include Disabled	include_disabled		boolean	Includes disabled cards. By default, all enabled cards owned by the merchant are returned.
Reference ID	reference_id		string	Limit results to cards associated with the reference_id supplied.
Sort Order	sort_order		string	Sorts the returned list by when the card was created with the specified order.

Returns

Name	Path	Type	Description
Cards	cards	array of object
ID	cards.card.id	string	The identifier of the object
Address Line 1	cards.card.billing_address.address_line_1	string	Fields that start with address_line provide the address's most specific details, like street number, street name, and building name.
Address Line 2	cards.card.billing_address.address_line_2	string	The second line of the address, if any.
Locality	cards.card.billing_address.locality	string	The city or town of the address.
Administrative District Level 1	cards.card.billing_address.administrative_district_level_1	string	A civil entity within the address's country. In the US, this is the state.
Postal Code	cards.card.billing_address.postal_code	string	The address's postal code.
Country	cards.card.billing_address.country	string	The address's country, in ISO 3166-1-alpha-2 format.
Fingerprint	cards.card.fingerprint	string	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
BIN	cards.card.bin	string	The first six digits of the card number, known as the Bank Identification Number (BIN).
Card Brand	cards.card.card_brand	string	The card's brand.
Card Type	cards.card.card_type	string	The type of the card.
Cardholder Name	cards.card.cardholder_name	string	The name of the cardholder.
Customer ID	cards.card.customer_id	string	The ID of a customer to be associated with the card.
Enabled	cards.card.enabled	boolean	Indicates whether or not an object can be used.
Expiration Month	cards.card.exp_month	integer	The expiration month of the associated card as an integer between 1 and 12.
Expiration Year	cards.card.exp_year	integer	The four-digit year of the card's expiration date.
Last 4	cards.card.last_4	string	The last 4 digits of the card number.
Prepaid Type	cards.card.prepaid_type	string	Indicates whether the Card is prepaid or not.
Reference ID	cards.card.reference_id	string	An optional user-defined reference ID that associates this card with another entity in an external system.
Version	cards.card.version	integer	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.

List catalog

Operation ID:

CatalogList

Returns a list of CatalogObjects that includes all objects of a set of desired types (for example, all CatalogItem and CatalogTax objects) in the catalog. ListCatalog does not return deleted catalog items.

Parameters

Name	Key	Required	Type	Description
Cursor	cursor		integer	The pagination cursor returned by a previous call to this endpoint.
Types	types		string	An optional case-insensitive, comma-separated list of object types to retrieve. The valid values are defined in the CatalogObjectType enum, including ITEM, ITEM_VARIATION, CATEGORY, DISCOUNT, TAX, MODIFIER, MODIFIER_LIST, or IMAGE. If this is unspecified, the operation returns objects of all the types at the version of the Square API used to make the request.

Returns

Name	Path	Type	Description
Objects	objects	array of object
Type	objects.type	string	The type of this object.
ID	objects.id	string	The unique, Square-issued identifier.
Updated At	objects.updated_at	string	Last modification timestamp in RFC 3339 format
Version	objects.version	integer	The current version of the object.
Is Deleted	objects.is_deleted	boolean	If true, the object has been deleted from the database. Must be false for new objects being inserted. When deleted, the updated_at field will equal the deletion time.
Present at All Locations	objects.present_at_all_locations	boolean	If true, this object is present at all locations (including future locations), except where specified in the absent_at_location_ids field. If false, this object is not present at any locations (including future locations), except where specified in the present_at_location_ids field. If not specified, defaults to true.
Name	objects.category_data.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.
Name	objects.tax_data.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.
Calculation Phase	objects.tax_data.calculation_phase	string	Whether the tax is calculated based on a payment's subtotal or total.
Inclusion Type	objects.tax_data.inclusion_type	string	Whether the tax is ADDITIVE or INCLUSIVE.
Percentage	objects.tax_data.percentage	string	The percentage in decimal form, using a '.' as the decimal separator and without a '%' sign. A value of 7.5 corresponds to 7.5%.
Enabled	objects.tax_data.enabled	boolean	Indicates whether or not an object can be used.

List customer groups

Operation ID:

CustomerGroupList

Retrieves the list of customer groups of a business.

Returns

Name	Path	Type	Description
Groups	groups	array of object
ID	groups.id	string	The unique, Square-issued identifier.
Name	groups.name	string	The name of the object.
Created At	groups.created_at	string	The event time in ISO 8601 format.
Updated At	groups.updated_at	string	Last modification timestamp in RFC 3339 format

List customer segments

Operation ID:

CustomerSegmentList

Retrieves the list of customer segments of a business.

Parameters

Name	Key	Required	Type	Description
Cursor	cursor		string	The pagination cursor returned by a previous call to this endpoint.
Limit	limit		integer	Upper limit on the number to return in the response.

Returns

Name	Path	Type	Description
Segments	segments	array of object
ID	segments.id	string	The unique, Square-issued identifier.
Name	segments.name	string	The name of the object.
Created At	segments.created_at	string	The event time in ISO 8601 format.
Updated At	segments.updated_at	string	Last modification timestamp in RFC 3339 format

List customers

Operation ID:

CustomerList

Lists customer profiles associated with a Square account. Under normal operating conditions, newly created or updated customer profiles become available for the listing operation in well under 30 seconds. Occasionally, propagation of the new or updated profiles can take closer to one minute or longer, especially during network incidents and outages.

Parameters

Name	Key	Required	Type	Description
Cursor	cursor		string	The pagination cursor returned by a previous call to this endpoint.
Limit	limit		integer	Upper limit on the number to return in the response.
Sort Field	sort_field		string	Indicates how customers should be sorted. The default value is DEFAULT.
Sort Order	sort_order		string	Sorts the returned list by when the card was created with the specified order.

Returns

Name	Path	Type	Description
Customers	customers	array of object
ID	customers.id	string	The unique, Square-issued identifier.
Created At	customers.created_at	string	The event time in ISO 8601 format.
Updated At	customers.updated_at	string	Last modification timestamp in RFC 3339 format
Given Name	customers.given_name	string	The given (i.e., first) name associated with the customer profile.
Family Name	customers.family_name	string	The family (i.e., last) name associated with the customer profile.
Email Address	customers.email_address	string	The email address associated with the customer profile.
Address Line 1	customers.address.address_line_1	string	The first line of the address.
Address Line 2	customers.address.address_line_2	string	The second line of the address, if any.
Locality	customers.address.locality	string	The city or town of the address.
Administrative District Level 1	customers.address.administrative_district_level_1	string	A civil entity within the address's country. In the US, this is the state.
Postal Code	customers.address.postal_code	string	The address's postal code.
Country	customers.address.country	string	The address's country, in ISO 3166-1-alpha-2 format.
Phone Number	customers.phone_number	string	The 11-digit phone number associated with the customer profile.
Reference ID	customers.reference_id	string	An optional second ID used to associate the customer profile with an entity in another system.
Note	customers.note	string	A custom note associated with the customer profile.
Email Unsubscribed	customers.preferences.email_unsubscribed	boolean	Indicates whether the customer has unsubscribed from marketing campaign emails. A value of true means that the customer chose to opt out of email marketing from the current Square seller or from all Square sellers. This value is read-only from the Customers API.
Creation Source	customers.creation_source	string	A creation source represents the method used to create the customer profile.
Group IDs	customers.group_ids	array of string
Segment IDs	customers.segment_ids	array of string
Version	customers.version	integer	The current version of the object.

List dispute evidence

Operation ID:

DisputeListEvidence

Returns a list of evidence associated with a dispute.

Parameters

Name	Key	Required	Type	Description
Dispute ID	dispute_id	True	string	The identifier of the dispute.

Returns

Name	Path	Type	Description
Evidence	evidence	array of object
ID	evidence.id	string	The unique, Square-issued identifier.
Dispute ID	evidence.dispute_id	string	The ID of the dispute the evidence is associated with.
Evidence Text	evidence.evidence_text	string	The raw text.
Evidence Type	evidence.evidence_type	string	The type of the evidence.
Uploaded At	evidence.uploaded_at	string	The time when the next action is due, in RFC 3339 format.
Evidence ID	evidence.evidence_id	string	The Square-generated ID of the evidence.
Filename	evidence.evidence_file.filename	string	The file name including the file extension
Filetype	evidence.evidence_file.filetype	string	Dispute evidence files must be application/pdf, image/heic, image/heif, image/jpeg, image/png, or image/tiff formats.
Cursor	cursor	string	Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query.

List disputes

Operation ID:

DisputeList

Returns a list of disputes associated with a particular account.

Parameters

Name	Key	Required	Type	Description
Cursor	cursor		string	The pagination cursor returned by a previous call to this endpoint.
States	states		string	The dispute states to filter the result. If not specified, the endpoint returns all open disputes (the dispute status is not INQUIRY_CLOSED, WON, or LOST).
Location ID	location_id		string	You can specify this optional filter to retrieve only the records belonging to a specific location.

Returns

Name	Path	Type	Description
Disputes	disputes	array of object
ID	disputes.id	string	The unique, Square-issued identifier.
Amount	disputes.amount_money.amount	integer	The amount.
Currency	disputes.amount_money.currency	string	The currency.
Reason	disputes.reason	string	The dispute reason why the cardholder initiated the dispute with their bank.
State	disputes.state	string	The current state.
Due At	disputes.due_at	string	The time when the next action is due, in RFC 3339 format.
Disputed Payments	disputes.disputed_payments	array of object
Payment ID	disputes.disputed_payments.payment_id	string	Square-generated unique ID of the payment being disputed.
Card Brand	disputes.card_brand	string	The card brand used in the disputed payment.
Created At	disputes.created_at	string	The event time in ISO 8601 format.
Updated At	disputes.updated_at	string	Last modification timestamp in RFC 3339 format
Brand Dispute ID	disputes.brand_dispute_id	string	The ID of the dispute in the card brand system, generated by the card brand.
Cursor	cursor	string	Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query.

List invoices

Operation ID:

InvoiceList

Returns a list of invoices for a given location.

Parameters

Name	Key	Required	Type	Description
Location ID	location_id		string	You can specify this optional filter to retrieve only the records belonging to a specific location.
Cursor	cursor		string	The pagination cursor returned by a previous call to this endpoint.
Limit	limit		integer	Upper limit on the number to return in the response.

Returns

Name	Path	Type	Description
Invoices	invoices	array of object
ID	invoices.id	string	The unique, Square-issued identifier.
Version	invoices.version	integer	The current version of the object.
Location ID	invoices.location_id	string	The identifier for the location.
Order ID	invoices.order_id	string	The ID of the order.
Payment Requests	invoices.payment_requests	array of object
UID	invoices.payment_requests.uid	string	The Square-generated ID of the payment request in an invoice.
Request Type	invoices.payment_requests.request_type	string	Identifies the payment request type. This type defines how the payment request amount is determined.
Due Date	invoices.payment_requests.due_date	string	The due date (in the invoice's time zone) for the payment request, in YYYY-MM-DD format.
Tipping Enabled	invoices.payment_requests.tipping_enabled	boolean	If set to true, the Square-hosted invoice page (the public_url field of the invoice) provides a place for the customer to pay a tip.
reminders	invoices.payment_requests.reminders	array of object	Reminders
UID	invoices.payment_requests.reminders.uid	string	A Square-assigned ID that uniquely identifies the reminder within the InvoicePaymentRequest.
Relative Scheduled Days	invoices.payment_requests.reminders.relative_scheduled_days	integer	The number of days before (a negative number) or after (a positive number) the payment request due_date when the reminder is sent.
Message	invoices.payment_requests.reminders.message	string	The reminder message.
Status	invoices.payment_requests.reminders.status	string	The status of the reminder.
Amount	invoices.payment_requests.computed_amount_money.amount	integer	The amount.
Currency	invoices.payment_requests.computed_amount_money.currency	string	The currency.
Amount	invoices.payment_requests.total_completed_amount_money.amount	integer	The amount.
Currency	invoices.payment_requests.total_completed_amount_money.currency	string	The currency.
Automatic Payment Source	invoices.payment_requests.automatic_payment_source	string	The payment method for an automatic payment.
Percentage Requested	invoices.payment_requests.percentage_requested	string	Specifies the amount for the payment request in percentage.
Card ID	invoices.payment_requests.card_id	string	The ID of the credit or debit card on file to charge for the payment request.
Invoice Number	invoices.invoice_number	string	A user-friendly invoice number.
Title	invoices.title	string	The title of the invoice.
Description	invoices.description	string	The description.
Scheduled At	invoices.scheduled_at	string	The timestamp when the invoice is scheduled for processing, in RFC 3339 format. After the invoice is published, Square processes the invoice on the specified date, according to the delivery method and payment request settings.
Status	invoices.status	string	The current verification status of this object.
Timezone	invoices.timezone	string	The time zone used to interpret calendar dates on the invoice, such as due_date. When an invoice is created, this field is set to the timezone specified for the seller location. The value cannot be changed.
Created At	invoices.created_at	string	The event time in ISO 8601 format.
Updated At	invoices.updated_at	string	Last modification timestamp in RFC 3339 format
Customer ID	invoices.primary_recipient.customer_id	string	The ID of a customer to be associated with the card.
Given Name	invoices.primary_recipient.given_name	string	The recipient's given (that is, first) name.
Family Name	invoices.primary_recipient.family_name	string	The recipient's family (that is, last) name.
Email Address	invoices.primary_recipient.email_address	string	The recipient's email address.
Phone Number	invoices.primary_recipient.phone_number	string	The recipient's phone number.
Card	invoices.accepted_payment_methods.card	boolean	Indicates whether credit card or debit card payments are accepted.
Square Gift Card	invoices.accepted_payment_methods.square_gift_card	boolean	Indicates whether Square gift card payments are accepted.
Bank Account	invoices.accepted_payment_methods.bank_account	boolean	Indicates whether bank transfer payments are accepted.
Custom Fields	invoices.custom_fields	array of object
Label	invoices.custom_fields.label	string	The label or title of the custom field.
Value	invoices.custom_fields.value	string	The text of the custom field.
Placement	invoices.custom_fields.placement	string	The location of the custom field on the invoice
Delivery Method	invoices.delivery_method	string	The delivery method that Square uses to send the invoice, reminders, and receipts to the customer.
Sale or Service Date	invoices.sale_or_service_date	string	The date of the sale or the date that the service is rendered, in YYYY-MM-DD format. This field can be used to specify a past or future date which is displayed on the invoice.
Public URL	invoices.public_url	string	The URL of the Square-hosted invoice page. After you publish the invoice using the PublishInvoice endpoint, Square hosts the invoice page and returns the page URL in the response.
Amount	invoices.next_payment_amount_money.amount	integer	The amount.
Currency	invoices.next_payment_amount_money.currency	string	The currency.
Cursor	cursor	string	Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query.

List payment refunds

Operation ID:

RefundList

Retrieves a list of refunds for the account making the request. Results are eventually consistent, and new refunds or changes to refunds might take several seconds to appear.

Parameters

Name	Key	Required	Type	Description
Begin Time	begin_time		string	The inclusive start time of the query on opened_at, in ISO 8601 format.
End Time	end_time		string	The exclusive end date of the query on opened_at, in ISO 8601 format.
Sort Order	sort_order		string	Sorts the returned list by when the card was created with the specified order.
Cursor	cursor		string	The pagination cursor returned by a previous call to this endpoint.
Location ID	location_id		string	You can specify this optional filter to retrieve only the records belonging to a specific location.
Status	status		string	If specified, only returns objects that match the specified statuses.
Source Type	source_type		string	If provided, only refunds with the given source type are returned.
Limit	limit		integer	Upper limit on the number to return in the response.

Returns

Name	Path	Type	Description
Refunds	refunds	array of object
ID	refunds.id	string	The unique, Square-issued identifier.
Status	refunds.status	string	The current verification status of this object.
Amount	refunds.amount_money.amount	integer	The amount.
Currency	refunds.amount_money.currency	string	The currency.
Payment ID	refunds.payment_id	string	The ID of the payment.
Order ID	refunds.order_id	string	The ID of the order.
Created At	refunds.created_at	string	The event time in ISO 8601 format.
Updated At	refunds.updated_at	string	Last modification timestamp in RFC 3339 format
Processing Fee	refunds.processing_fee	array of object
Effective At	refunds.processing_fee.effective_at	string	The timestamp of when the fee takes effect, in RFC 3339 format.
Type	refunds.processing_fee.type	string	The type of this object.
Amount	refunds.processing_fee.amount_money.amount	integer	The amount.
Currency	refunds.processing_fee.amount_money.currency	string	The currency.
Location ID	refunds.location_id	string	The identifier for the location.
Reason	refunds.reason	string	The dispute reason why the cardholder initiated the dispute with their bank.
Cursor	cursor	string	Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query.

List payments

Operation ID:

PaymentList

Retrieves a list of payments taken by the account making the request. Results are eventually consistent, and new payments or changes to payments might take several seconds to appear.

Parameters

Name	Key	Required	Type	Description
Begin Time	begin_time		string	The inclusive start time of the query on opened_at, in ISO 8601 format.
End Time	end_time		string	The exclusive end date of the query on opened_at, in ISO 8601 format.
Sort Order	sort_order		string	Sorts the returned list by when the card was created with the specified order.
Cursor	cursor		string	The pagination cursor returned by a previous call to this endpoint.
Location ID	location_id		string	You can specify this optional filter to retrieve only the records belonging to a specific location.
Total	total		integer	The exact amount in the total_money for a payment.
Last 4	last_4		string	The last four digits of a payment card.
Card Brand	card_brand		string	The brand of the payment card (for example, VISA).
Limit	limit		integer	Upper limit on the number to return in the response.

Returns

Name	Path	Type	Description
Payments	payments	array of object
ID	payments.id	string	The unique, Square-issued identifier.
Created At	payments.created_at	string	The event time in ISO 8601 format.
Updated At	payments.updated_at	string	Last modification timestamp in RFC 3339 format
Amount	payments.amount_money.amount	integer	The amount.
Currency	payments.amount_money.currency	string	The currency.
Status	payments.status	string	The current verification status of this object.
Delay Duration	payments.delay_duration	string	The duration of time after the payment's creation when Square automatically applies the delay_action to the payment.
Source Type	payments.source_type	string	The source type for this payment.
Status	payments.card_details.status	string	The card payment's current state. The state can be AUTHORIZED, CAPTURED, VOIDED, or FAILED.
Card Brand	payments.card_details.card.card_brand	string	The card's brand.
last_4	payments.card_details.card.last_4	string	The last 4 digits of the card number.
Exp Month	payments.card_details.card.exp_month	integer	The expiration month of the associated card as an integer between 1 and 12.
Exp Year	payments.card_details.card.exp_year	integer	The four-digit year of the card's expiration date.
Fingerprint	payments.card_details.card.fingerprint	string	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
Card Type	payments.card_details.card.card_type	string	The type of the card.
Prepaid Type	payments.card_details.card.prepaid_type	string	Indicates whether the Card is prepaid or not.
BIN	payments.card_details.card.bin	string	The first six digits of the card number, known as the Bank Identification Number (BIN)
Entry Method	payments.card_details.entry_method	string	The method used to enter the card's details for the payment. The method can be KEYED, SWIPED, EMV, ON_FILE, or CONTACTLESS.
Cvv Status	payments.card_details.cvv_status	string	The status code returned from the Card Verification Value (CVV) check. The code can be CVV_ACCEPTED, CVV_REJECTED, or CVV_NOT_CHECKED.
Avs Status	payments.card_details.avs_status	string	The status code returned from the Address Verification System (AVS) check. The code can be AVS_ACCEPTED, AVS_REJECTED, or AVS_NOT_CHECKED.
Auth Result Code	payments.card_details.auth_result_code	string	The status code returned by the card issuer that describes the payment's authorization status.
Statement Description	payments.card_details.statement_description	string	The statement description sent to the card networks.
Authorized At	payments.card_details.card_payment_timeline.authorized_at	string	The timestamp when the payment was authorized, in RFC 3339 format.
Captured At	payments.card_details.card_payment_timeline.captured_at	string	The timestamp when the payment was captured, in RFC 3339 format.
Location ID	payments.location_id	string	The identifier for the location.
Order ID	payments.order_id	string	The ID of the order.
Processing Fee	payments.processing_fee	array of object
Effective At	payments.processing_fee.effective_at	string	The timestamp of when the fee takes effect, in RFC 3339 format.
Type	payments.processing_fee.type	string	The type of this object.
Amount	payments.processing_fee.amount_money.amount	integer	The amount.
Currency	payments.processing_fee.amount_money.currency	string	The currency.
Note	payments.note	string	A custom note associated with the customer profile.
Amount	payments.total_money.amount	integer	The amount.
Currency	payments.total_money.currency	string	The currency.
Amount	payments.approved_money.amount	integer	The amount.
Currency	payments.approved_money.currency	string	The currency.
Receipt Number	payments.receipt_number	string	The payment's receipt number. The field is missing if a payment is canceled.
Receipt URL	payments.receipt_url	string	The URL for the payment's receipt. The field is only populated for COMPLETED payments.
Delay Action	payments.delay_action	string	The action to be applied to the payment when the delay_duration has elapsed.
Delayed Until	payments.delayed_until	string	The read-only timestamp of when the delay_action is automatically applied, in RFC 3339 format.
Team Member ID	payments.team_member_id	string	The ID of the TeamMember object for the team member associated with the object.
Square Product	payments.application_details.square_product	string	The Square product, such as Square Point of Sale (POS), Square Invoices, or Square Virtual Terminal.
Application ID	payments.application_details.application_id	string	The Square ID assigned to the application used to take the payment. Application developers can use this information to identify payments that their application processed. For example, if a developer uses a custom application to process payments, this field contains the application ID from the Developer Dashboard. If a seller uses a Square App Marketplace application to process payments, the field contains the corresponding application ID.
Version Token	payments.version_token	string	Used for optimistic concurrency. This opaque token identifies a specific version of the Payment object.

List subscription events

Operation ID:

SubscriptionListEvents

Lists all events for a specific subscription.

Parameters

Name	Key	Required	Type	Description
Subscription ID	subscription_id	True	string	The identifier of the subscription.

Returns

Name	Path	Type	Description
Subscription Events	subscription_events	array of object
ID	subscription_events.id	string	The unique, Square-issued identifier.
Subscription Event Type	subscription_events.subscription_event_type	string	Type of the subscription event.
Effective Date	subscription_events.effective_date	string	The date, in YYYY-MM-DD format, when the subscription event went into effect.
Plan ID	subscription_events.plan_id	string	The ID of the associated subscription plan

Pay order (Beta)

Operation ID:

OrderPay

Pay for an order using one or more approved payments or settle an order with a total of 0. The total of the payment_ids listed in the request must be equal to the order total. Orders with a total amount of 0 can be marked as paid by specifying an empty array of payment_ids in the request.

Parameters

Name	Key	Required	Type	Description
Order ID	order_id	True	string	The identifier of the order.
Idempotency Key	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).
Payment IDs	payment_ids		array of string

Returns

Name	Path	Type	Description
ID	order.id	string	The unique, Square-issued identifier.
Location ID	order.location_id	string	The identifier of the location.
Line Items	order.line_items	array of object
UID	order.line_items.uid	string	The Square-generated ID.
Quantity	order.line_items.quantity	string	The number of items affected by the physical count as a decimal string. The number can support up to 5 digits after the decimal point.
Name	order.line_items.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.
Amount	order.line_items.base_price_money.amount	integer	The amount.
Currency	order.line_items.base_price_money.currency	string	The currency.
Amount	order.line_items.gross_sales_money.amount	integer	The amount.
Currency	order.line_items.gross_sales_money.currency	string	The currency.
Amount	order.line_items.total_tax_money.amount	integer	The amount.
Currency	order.line_items.total_tax_money.currency	string	The currency.
Amount	order.line_items.total_discount_money.amount	integer	The amount.
Currency	order.line_items.total_discount_money.currency	string	The currency.
Amount	order.line_items.total_money.amount	integer	The amount.
Currency	order.line_items.total_money.currency	string	The currency.
Created At	order.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	order.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Version	order.version	integer	The current version of this object.
Amount	order.total_tax_money.amount	integer	The amount.
Currency	order.total_tax_money.currency	string	The currency.
Amount	order.total_discount_money.amount	integer	The amount.
Currency	order.total_discount_money.currency	string	The currency.
Amount	order.total_money.amount	integer	The amount.
Currency	order.total_money.currency	string	The currency.
Closed At	order.closed_at	string	The time when closed, in ISO 8601 format.
Tenders	order.tenders	array of object
ID	order.tenders.id	string	The identifier of the object
Location ID	order.tenders.location_id	string	The location ID for a recipient (other than the merchant) receiving a portion of this tender.
Transaction ID	order.tenders.transaction_id	string	The ID of the tender's associated transaction.
Created At	order.tenders.created_at	string	The timestamp when created, in RFC 3339 format.
Amount	order.tenders.amount_money.amount	integer	The amount.
Currency	order.tenders.amount_money.currency	string	The currency.
Type	order.tenders.type	string	Indicates the type.
Status	order.tenders.card_details.status	string	The credit card payment's current state (such as AUTHORIZED or CAPTURED)
Card Brand	order.tenders.card_details.card.card_brand	string	The card's brand.
last_4	order.tenders.card_details.card.last_4	string	The last 4 digits of the card number.
Exp Month	order.tenders.card_details.card.exp_month	integer	The expiration month of the associated card as an integer between 1 and 12.
Exp Year	order.tenders.card_details.card.exp_year	integer	The four-digit year of the card's expiration date.
Fingerprint	order.tenders.card_details.card.fingerprint	string	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
Entry Method	order.tenders.card_details.entry_method	string	The method used to enter the card's details for the transaction.
Payment ID	order.tenders.payment_id	string	Square-generated unique ID of the payment.
Amount	order.total_service_charge_money.amount	integer	The amount.
Currency	order.total_service_charge_money.currency	string	The currency.
Amount	order.net_amounts.total_money.amount	integer	The amount.
Currency	order.net_amounts.total_money.currency	string	The currency.
Amount	order.net_amounts.tax_money.amount	integer	The amount.
Currency	order.net_amounts.tax_money.currency	string	The currency.
Amount	order.net_amounts.discount_money.amount	integer	The amount.
Currency	order.net_amounts.discount_money.currency	string	The currency.
Amount	order.net_amounts.tip_money.amount	integer	The amount.
Currency	order.net_amounts.tip_money.currency	string	The currency.
Amount	order.net_amounts.service_charge_money.amount	integer	The amount.
Currency	order.net_amounts.service_charge_money.currency	string	The currency.
Name	order.source.name	string	The name.
State	order.state	string	The current state.

Publish invoice

Operation ID:

InvoicePublish

Publishes the specified draft invoice. After an invoice is published, Square follows up based on the invoice configuration. For example, Square sends the invoice to the customer's email address, charges the customer's card on file, or does nothing. Square also makes the invoice available on a Square-hosted invoice page.

Parameters

Name	Key	Required	Type	Description
Invoice ID	invoice_id	True	string	The identifier of the invoice.
Version	version		integer	The version.
Idempotency Key	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).

Returns

Name	Path	Type	Description
ID	invoice.id	string	The unique, Square-issued identifier.
Version	invoice.version	integer	The current version of this object.
Location ID	invoice.location_id	string	The identifier of the location.
Order ID	invoice.order_id	string	The ID of the order.
Payment Requests	invoice.payment_requests	array of object
UID	invoice.payment_requests.uid	string	The Square-generated ID.
Request Type	invoice.payment_requests.request_type	string	Identifies the payment request type. This type defines how the payment request amount is determined.
Due Date	invoice.payment_requests.due_date	string	The due date for the payment request, in YYYY-MM-DD format.
Tipping Enabled	invoice.payment_requests.tipping_enabled	boolean	If set to true, provides a place for the customer to pay a tip.
Reminders	invoice.payment_requests.reminders	array of object
UID	invoice.payment_requests.reminders.uid	string	A Square-assigned ID.
Relative Scheduled Days	invoice.payment_requests.reminders.relative_scheduled_days	integer	The number of days before (a negative number) or after (a positive number) the payment request due_date when the reminder is sent.
Message	invoice.payment_requests.reminders.message	string	The message.
Status	invoice.payment_requests.reminders.status	string	The current status.
Amount	invoice.payment_requests.computed_amount_money.amount	integer	The amount.
Currency	invoice.payment_requests.computed_amount_money.currency	string	The currency.
Amount	invoice.payment_requests.total_completed_amount_money.amount	integer	The amount.
Currency	invoice.payment_requests.total_completed_amount_money.currency	string	The currency.
Automatic Payment Source	invoice.payment_requests.automatic_payment_source	string	The payment method for an automatic payment.
Invoice Number	invoice.invoice_number	string	A user-friendly invoice number. The value is unique within a location. If not provided when creating an invoice, Square assigns a value.
Title	invoice.title	string	The title.
Description	invoice.description	string	The description.
Scheduled At	invoice.scheduled_at	string	The timestamp when the processing is scheduled, in RFC 3339 format.
Status	invoice.status	string	The current verification status of this object.
Timezone	invoice.timezone	string	The time zone used to interpret calendar dates. When an invoice is created, this field is set to the timezone specified for the seller location. The value cannot be changed.
Created At	invoice.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	invoice.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Customer ID	invoice.primary_recipient.customer_id	string	The ID of the customer associated with the order.
Given Name	invoice.primary_recipient.given_name	string	The recipient's given (that is, first) name.
Family Name	invoice.primary_recipient.family_name	string	The recipient's family (that is, last) name.
Email Address	invoice.primary_recipient.email_address	string	The recipient's email address.
Phone Number	invoice.primary_recipient.phone_number	string	The recipient's phone number.
Public URL	invoice.public_url	string	The URL of the Square-hosted invoice page. After you publish the invoice using the PublishInvoice endpoint, Square hosts the invoice page and returns the page URL in the response.
Card	invoice.accepted_payment_methods.card	boolean	Indicates whether credit card or debit card payments are accepted.
Square Gift Card	invoice.accepted_payment_methods.square_gift_card	boolean	Indicates whether Square gift card payments are accepted.
Bank Account	invoice.accepted_payment_methods.bank_account	boolean	Indicates whether bank transfer payments are accepted.
Custom Fields	invoice.custom_fields	array of object
Label	invoice.custom_fields.label	string	The label or title of the custom field.
Value	invoice.custom_fields.value	string	The text of the custom field.
Placement	invoice.custom_fields.placement	string	The location of the custom field on the invoice.
Delivery Method	invoice.delivery_method	string	The delivery method that Square uses to send the invoice, reminders, and receipts to the customer. After the invoice is published, Square processes the invoice based on the delivery method and payment request settings, either immediately or on the scheduled_at date, if specified.
Sale or Service Date	invoice.sale_or_service_date	string	The date of the sale or the date that the service is rendered, in YYYY-MM-DD format. This field can be used to specify a past or future date which is displayed on the invoice.

Refund payment

Operation ID:

RefundPayment

Refunds a payment. You can refund the entire payment amount or a portion of it. You can use this endpoint to refund a card payment or record a refund of a cash or external payment.

Parameters

Name	Key	Required	Type	Description
Idempotency Key	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).
Payment ID	payment_id		string	The unique ID of the payment being refunded.
Amount	amount		integer	The amount of money to accept for this payment, not including tip_money.
Currency	currency		string	The 3-character ISO 4217 currency code.
Amount	amount		integer	The amount of money to accept for this payment, not including tip_money.
Currency	currency		string	The 3-character ISO 4217 currency code.
Reason	reason		string	A description of the reason for the refund.

Returns

Name	Path	Type	Description
ID	refund.id	string	The unique, Square-issued identifier.
Status	refund.status	string	The current verification status of this object.
Amount	refund.amount_money.amount	integer	The amount.
Currency	refund.amount_money.currency	string	The currency.
Payment ID	refund.payment_id	string	The unique ID of the payment.
Order ID	refund.order_id	string	The ID of the order.
Created At	refund.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	refund.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Amount	refund.app_fee_money.amount	integer	The amount.
Currency	refund.app_fee_money.currency	string	The currency.
Location ID	refund.location_id	string	The identifier of the location.
Reason	refund.reason	string	The reason for this object.

Register domain for Apple Pay

Operation ID:

ApplePayRegister

Activates a domain for use with Apple Pay on the Web and Square. A validation is performed on this domain by Apple to ensure that it is properly set up as an Apple Pay enabled domain.

Parameters

Name	Key	Required	Type	Description
Domain Name	domain_name	True	string	A domain name as described in RFC-1034 that will be registered with Apple Pay.

Returns

Name	Path	Type	Description
Status	status	string	The status of the domain registration.

Remove group from customer

Operation ID:

CustomerRemoveGroup

Removes a group membership from a customer. The customer is identified by the customer_id value and the customer group is identified by the group_id value.

Parameters

Name	Key	Required	Type	Description
Customer ID	customer_id	True	string	The identifier of the customer.
Group ID	group_id	True	string	The identifier of the group.

Returns

response

object

Resume subscription

Operation ID:

SubscriptionResume

Resumes a deactivated subscription.

Parameters

Name	Key	Required	Type	Description
Subscription ID	subscription_id	True	string	The identifier of the subscription.

Returns

Name	Path	Type	Description
ID	subscription.id	string	The unique, Square-issued identifier.
Location ID	subscription.location_id	string	The identifier of the location.
Plan ID	subscription.plan_id	string	The ID of the associated subscription plan.
Customer ID	subscription.customer_id	string	The ID of this object representing the customer.
Status	subscription.status	string	The current verification status of this object.
Amount	subscription.price_override_money.amount	integer	The amount.
Currency	subscription.price_override_money.currency	string	The currency.
Version	subscription.version	integer	The current version of this object.
Created At	subscription.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Timezone	subscription.timezone	string	The time zone used to interpret calendar dates. When an invoice is created, this field is set to the timezone specified for the seller location. The value cannot be changed.
Name	subscription.source.name	string	The name.

Retrieve card

Operation ID:

CardRetrieve

Retrieves details for a specific Card.

Parameters

Name	Key	Required	Type	Description
Card ID	card_id	True	string	The identifier of the card.

Returns

Name	Path	Type	Description
ID	card.id	string	The unique, Square-issued identifier.
Address Line 1	card.billing_address.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.
Address Line 2	card.billing_address.address_line_2	string	The second line of the address, if any.
Locality	card.billing_address.locality	string	The city or town of the address.
Administrative District Level 1	card.billing_address.administrative_district_level_1	string	A civil entity within the address's country. In the US, this is the state.
Postal Code	card.billing_address.postal_code	string	The address's postal code.
Country	card.billing_address.country	string	The address's country, in ISO 3166-1-alpha-2 format.
Fingerprint	card.fingerprint	string	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
BIN	card.bin	string	The first six digits of the card number, known as the Bank Identification Number (BIN).
Card Brand	card.card_brand	string	The card's brand.
Card Type	card.card_type	string	The type of the card.
Cardholder Name	card.cardholder_name	string	The name of the cardholder.
Customer ID	card.customer_id	string	The ID of this object representing the customer.
Enabled	card.enabled	boolean	Whether enabled.
Exp Month	card.exp_month	integer	The expiration month of the associated card as an integer between 1 and 12.
Exp Year	card.exp_year	integer	The four-digit year of the card's expiration date.
Last 4	card.last_4	string	The last 4 digits of the card number.
Prepaid Type	card.prepaid_type	string	Indicates whether the Card is prepaid or not.
Reference ID	card.reference_id	string	An optional user-defined reference ID.
Version	card.version	integer	The current version of this object.

Retrieve catalog object

Operation ID:

CatalogRetrieve

Returns a single CatalogItem as a CatalogObject based on the provided ID. The returned object includes all of the relevant CatalogItem information including: CatalogItemVariation children, references to its CatalogModifierList objects, and the ids of any CatalogTax objects that apply to it.

Parameters

Name	Key	Required	Type	Description
Object ID	object_id	True	string	The identifier of the object.
Include Related Objects	include_related_objects		boolean	If true, the response will include additional objects that are related to the requested object, as follows: If the object field of the response contains a CatalogItem, its associated CatalogCategory, CatalogTax, CatalogImage and CatalogModifierList objects will be returned in the related_objects field of the response. If the object field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in the related_objects field of the response.

Returns

Name	Path	Type	Description
Type	object.type	string	The type of this object.
ID	object.id	string	The unique, Square-issued identifier.
Updated At	object.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Version	object.version	integer	The current version of this object.
Is Deleted	object.is_deleted	boolean	If true, the object has been deleted from the database. Must be false for new objects being inserted. When deleted, the updated_at field will equal the deletion time.
present_at_all_locations	object.present_at_all_locations	boolean	If true, this object is present at all locations (including future locations), except where specified in the absent_at_location_ids field. If false, this object is not present at any locations (including future locations), except where specified in the present_at_location_ids field. If not specified, defaults to true.
Name	object.item_data.name	string	The name.
Description	object.item_data.title	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.
Category ID	object.item_data.category_id	string	The ID of the item's category, if any.
Tax IDs	object.item_data.tax_ids	array of string
Variations	object.item_data.variations	array of object
Type	object.item_data.variations.type	string	The type of this object.
ID	object.item_data.variations.id	string	An identifier to reference this object in the catalog.
Updated At	object.item_data.variations.updated_at	string	Last modification timestamp in RFC 3339 format.
Version	object.item_data.variations.version	integer	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.
Is Deleted	object.item_data.variations.is_deleted	boolean	If true, the object has been deleted from the database. Must be false for new objects being inserted. When deleted, the updated_at field will equal the deletion time.
Present at All Locations	object.item_data.variations.present_at_all_locations	boolean	If true, this object is present at all locations (including future locations), except where specified in the absent_at_location_ids field. If false, this object is not present at any locations (including future locations), except where specified in the present_at_location_ids field. If not specified, defaults to true.
Item ID	object.item_data.variations.item_variation_data.item_id	string	The ID of the CatalogItem associated with this item variation.
Name	object.item_data.variations.item_variation_data.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	object.item_data.variations.item_variation_data.ordinal	integer	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.
Pricing Type	object.item_data.variations.item_variation_data.pricing_type	string	Indicates whether the item variation's price is fixed or determined at the time of sale.
Amount	object.item_data.variations.item_variation_data.price_money.amount	integer	The amount.
Currency	object.item_data.variations.item_variation_data.price_money.currency	string	The currency.

Retrieve customer

Operation ID:

CustomerRetrieve

Returns details for a single customer.

Parameters

Name	Key	Required	Type	Description
Customer ID	customer_id	True	string	The identifier of the customer.

Returns

Name	Path	Type	Description
ID	customer.id	string	The unique, Square-issued identifier.
Created At	customer.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	customer.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Given Name	customer.given_name	string	The given (i.e., first) name associated with the customer profile.
Family Name	customer.family_name	string	The family (i.e., last) name associated with the customer profile.
Email Address	customer.email_address	string	The email address associated with the customer profile.
Address Line 1	customer.address.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.
Address Line 2	customer.address.address_line_2	string	The second line of the address, if any.
Locality	customer.address.locality	string	The city or town of the address.
Administrative District Level 1	customer.address.administrative_district_level_1	string	A civil entity within the address's country. In the US, this is the state.
Postal Code	customer.address.postal_code	string	The address's postal code.
Country	customer.address.country	string	The address's country, in ISO 3166-1-alpha-2 format.
Phone Number	customer.phone_number	string	The 11-digit phone number associated with the customer profile.
Reference ID	customer.reference_id	string	An optional user-defined reference ID.
Note	customer.note	string	A custom note associated with the customer profile.
Email Unsubscribed	customer.preferences.email_unsubscribed	boolean	Indicates whether the customer has unsubscribed from marketing campaign emails. A value of true means that the customer chose to opt out of email marketing from the current Square seller or from all Square sellers.
Creation Source	customer.creation_source	string	A creation source represents the method used to create the customer profile.
Group IDs	customer.group_ids	array of string
Segment IDs	customer.segment_ids	array of string
Version	customer.version	integer	The current version of this object.

Retrieve customer group

Operation ID:

CustomerGroupRetrieve

Retrieves a specific customer group.

Parameters

Name	Key	Required	Type	Description
Group ID	group_id	True	string	The identifier of the group.

Returns

Name	Path	Type	Description
ID	group.id	string	The unique, Square-issued identifier.
Name	group.name	string	The name of the object.
Created At	group.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	group.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.

Retrieve customer segment

Operation ID:

CustomerSegmentRetrieve

Retrieves a specific customer segment.

Parameters

Name	Key	Required	Type	Description
Segment ID	segment_id	True	string	The identifier of the segment.

Returns

Name	Path	Type	Description
ID	segment.id	string	The unique, Square-issued identifier.
Name	segment.name	string	The name of the object.
Created At	segment.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	segment.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.

Retrieve dispute

Operation ID:

DisputeRetrieve

Returns details about a specific dispute.

Parameters

Name	Key	Required	Type	Description
Dispute ID	dispute_id	True	string	The identifier of the dispute.

Returns

Name	Path	Type	Description
ID	dispute.id	string	The unique, Square-issued identifier.
Amount	dispute.amount_money.amount	integer	The amount.
Currency	dispute.amount_money.currency	string	The currency.
Reason	dispute.reason	string	The reason for this object.
State	dispute.state	string	The current state.
Due At	dispute.due_at	string	The time when the next action is due, in RFC 3339 format.
Disputed Payments	dispute.disputed_payments	array of object
Payment ID	dispute.disputed_payments.payment_id	string	Square-generated unique ID of the payment.
Card Brand	dispute.card_brand	string	The card's brand.
Created At	dispute.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	dispute.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Brand Dispute ID	dispute.brand_dispute_id	string	The ID of the dispute in the card brand system, generated by the card brand.

Retrieve dispute evidence

Operation ID:

DisputeRetrieveEvidence

Returns the evidence metadata specified by the evidence ID in the request URL path. You must maintain a copy of the evidence you upload if you want to reference it later. You cannot download the evidence after you upload it.

Parameters

Name	Key	Required	Type	Description
Dispute ID	dispute_id	True	string	The identifier of the dispute.
Evidence ID	evidence_id	True	string	The identifier of the evidence.

Returns

Name	Path	Type	Description
ID	evidence.id	string	The unique, Square-issued identifier.
Dispute ID	evidence.dispute_id	string	The ID of the dispute the evidence is associated with.
Filename	evidence.evidence_file.filename	string	Dispute evidence files must be application/pdf, image/heic, image/heif, image/jpeg, image/png, or image/tiff formats.
Filetype	evidence.evidence_file.filetype	string	The file name including the file extension.
Evidence Type	evidence.evidence_type	string	The type pf evidence.
Uploaded At	evidence.uploaded_at	string	The time when the next action is due, in RFC 3339 format.

Retrieve inventory adjustment

Operation ID:

InventoryRetrieveAdjustment

Returns the InventoryAdjustment object with the provided adjustment_id.

Parameters

Name	Key	Required	Type	Description
Adjustment ID	adjustment_id	True	string	The identifier of the adjustment.

Returns

Name	Path	Type	Description
ID	adjustment.id	string	The unique, Square-issued identifier.
Reference ID	adjustment.reference_id	string	An optional user-defined reference ID.
From State	adjustment.from_state	string	The inventory state of the related quantity of items before the adjustment.
To State	adjustment.to_state	string	The inventory state of the related quantity of items after the adjustment.
Location ID	adjustment.location_id	string	The identifier of the location.
Catalog Object ID	adjustment.catalog_object_id	string	The Square-generated ID of the CatalogObject being tracked.
Catalog Object Type	adjustment.catalog_object_type	string	The type of the CatalogObject being tracked.
Quantity	adjustment.quantity	string	The number of items affected by the adjustment as a decimal string. Can support up to 5 digits after the decimal point.
Amount	adjustment.total_price_money.amount	integer	The amount.
Currency	adjustment.total_price_money.currency	string	The currency.
Occurred At	adjustment.occurred_at	string	A client-generated RFC 3339-formatted timestamp that indicates when the inventory adjustment took place. For inventory adjustment updates, the occurred_at timestamp cannot be older than 24 hours or in the future relative to the time of the request.
Created At	adjustment.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Product	adjustment.source.product	string	Product type for the application.
Application ID	adjustment.source.application_id	string	Read-only Square ID assigned to the application.
Name	adjustment.source.name	string	The name.
Employee ID	adjustment.employee_id	string	The Square-generated ID of the Employee.

Retrieve inventory count

Operation ID:

InventoryRetrieveCount

Retrieves the current calculated stock count for a given CatalogObject at a given set of Locations.

Parameters

Name	Key	Required	Type	Description
Catalog Object ID	catalog_object_id	True	string	The identifier of the catalog object.
Location IDs	location_ids		string	The Location IDs to look up as a comma-separated list. An empty list queries all locations.
Cursor	cursor		string	The pagination cursor returned by a previous call to this endpoint.

Returns

Name	Path	Type	Description
Counts	counts	array of object
Catalog Object ID	counts.catalog_object_id	string	The Square-generated ID of the CatalogObject being tracked.
Catalog Object Type	counts.catalog_object_type	string	The type of the CatalogObject being tracked.
State	counts.state	string	The current state.
Location ID	counts.location_id	string	The identifier for the location.
Quantity	counts.quantity	string	The number of items affected by the estimated count as a decimal string. Can support up to 5 digits after the decimal point.
Calculated At	counts.calculated_at	string	An RFC 3339-formatted timestamp that indicates when the most recent physical count or adjustment affecting the estimated count is received.

Retrieve inventory physical count

Operation ID:

InventoryRetrievePhysicalCount

Returns the InventoryPhysicalCount object with the provided physical_count_id.

Parameters

Name	Key	Required	Type	Description
Physical Count ID	physical_count_id	True	string	The identifier of the physical count.

Returns

Name	Path	Type	Description
ID	count.id	string	The unique, Square-issued identifier.
Reference ID	count.reference_id	string	An optional user-defined reference ID.
Catalog Object ID	count.catalog_object_id	string	The Square-generated ID of the CatalogObject being tracked.
Catalog Object Type	count.catalog_object_type	string	The type of the CatalogObject being tracked.
State	count.state	string	The current state.
Location ID	count.location_id	string	The identifier of the location.
Quantity	count.quantity	string	The number of items affected by the adjustment as a decimal string. Can support up to 5 digits after the decimal point.
Product	count.source.product	string	Product type for the application.
Application ID	count.source.application_id	string	Read-only Square ID assigned to the application.
Name	count.source.name	string	The name.
Employee ID	count.employee_id	string	The Square-generated ID of the Employee.
Occurred At	count.occurred_at	string	A client-generated RFC 3339-formatted timestamp that indicates when the inventory adjustment took place. For inventory adjustment updates, the occurred_at timestamp cannot be older than 24 hours or in the future relative to the time of the request.
Created At	count.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.

Retrieve inventory transfer (Beta)

Operation ID:

InventoryRetrieveTransfer

Returns the InventoryTransfer object with the provided transfer_id.

Parameters

Name	Key	Required	Type	Description
Transfer ID	transfer_id	True	string	The identifier of the transfer.

Returns

Name	Path	Type	Description
ID	transfer.id	string	The unique, Square-issued identifier.
Catalog Object ID	transfer.catalog_object_id	string	The Square-generated ID of the CatalogObject being tracked.
Catalog Object Type	transfer.catalog_object_type	string	The type of the CatalogObject being tracked.
Created At	transfer.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Employee ID	transfer.employee_id	string	The Square-generated ID of the Employee.
From Location ID	transfer.from_location_id	string	The Square-generated ID of the Location where the related quantity of items was tracked before the transfer.
To Location ID	transfer.to_location_id	string	The Square-generated ID of the Location where the related quantity of items was tracked after the transfer.
Occurred At	transfer.occurred_at	string	A client-generated RFC 3339-formatted timestamp that indicates when the inventory adjustment took place. For inventory adjustment updates, the occurred_at timestamp cannot be older than 24 hours or in the future relative to the time of the request.
Quantity	transfer.quantity	string	The number of items affected by the adjustment as a decimal string. Can support up to 5 digits after the decimal point.
Reference ID	transfer.reference_id	string	An optional user-defined reference ID.
Product	transfer.source.product	string	Product type for the application.
Application ID	transfer.source.application_id	string	Read-only Square ID assigned to the application.
Name	transfer.source.name	string	The name.
State	transfer.state	string	The current state.

Retrieve order

Operation ID:

OrderRetrieve

Retrieves an Order by ID.

Parameters

Name	Key	Required	Type	Description
Order ID	order_id	True	string	The identifier of the order.

Returns

Name	Path	Type	Description
ID	order.id	string	The unique, Square-issued identifier.
Location ID	order.location_id	string	The identifier of the location.
Line Items	order.line_items	array of object
UID	order.line_items.uid	string	The Square-generated ID.
Quantity	order.line_items.quantity	string	The number of items affected by the physical count as a decimal string. The number can support up to 5 digits after the decimal point.
Name	order.line_items.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.
Amount	order.line_items.base_price_money.amount	integer	The amount.
Currency	order.line_items.base_price_money.currency	string	The currency.
Amount	order.line_items.gross_sales_money.amount	integer	The amount.
Currency	order.line_items.gross_sales_money.currency	string	The currency.
Amount	order.line_items.total_tax_money.amount	integer	The amount.
Currency	order.line_items.total_tax_money.currency	string	The currency.
Amount	order.line_items.total_discount_money.amount	integer	The amount.
Currency	order.line_items.total_discount_money.currency	string	The currency.
Amount	order.line_items.total_money.amount	integer	The amount.
Currency	order.line_items.total_money.currency	string	The currency.
Amount	order.line_items.variation_total_price_money.amount	integer	The amount.
Currency	order.line_items.variation_total_price_money.currency	string	The currency.
Applied Discounts	order.line_items.applied_discounts	array of object
UID	order.line_items.applied_discounts.uid	string	A Square-assigned ID.
Discount UID	order.line_items.applied_discounts.discount_uid	string	The uid of the discount that the applied discount represents.
Amount	order.line_items.applied_discounts.applied_money.amount	integer	The amount.
Currency	order.line_items.applied_discounts.applied_money.currency	string	The currency.
Discounts	order.discounts	array of object
UID	order.discounts.uid	string	The Square-generated ID.
Name	order.discounts.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.
Percentage	order.discounts.percentage	string	The percentage in decimal form, using a '.' as the decimal separator and without a '%' sign. A value of 7.5 corresponds to 7.5%.
Amount	order.discounts.applied_money.amount	integer	The amount.
Currency	order.discounts.applied_money.currency	string	The currency.
Type	order.discounts.type	string	Indicates the type.
Scope	order.discounts.scope	string	Indicates the current level.
Created At	order.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	order.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
State	order.state	string	The current state.
Version	order.version	integer	The current version of this object.
Amount	order.total_tax_money.amount	integer	The amount.
Currency	order.total_tax_money.currency	string	The currency.
Amount	order.total_discount_money.amount	integer	The amount.
Currency	order.total_discount_money.currency	string	The currency.
Amount	order.total_tip_money.amount	integer	The amount.
Currency	order.total_tip_money.currency	string	The currency.
Amount	order.total_money.amount	integer	The amount.
Currency	order.total_money.currency	string	The currency.
Amount	order.total_service_charge_money.amount	integer	The amount.
Currency	order.total_service_charge_money.currency	string	The currency.
Amount	order.net_amounts.total_money.amount	integer	The amount.
Currency	order.net_amounts.total_money.currency	string	The currency.
Amount	order.net_amounts.tax_money.amount	integer	The amount.
Currency	order.net_amounts.tax_money.currency	string	The currency.
Amount	order.net_amounts.discount_money.amount	integer	The amount.
Currency	order.net_amounts.discount_money.currency	string	The currency.
Amount	order.net_amounts.tip_money.amount	integer	The amount.
Currency	order.net_amounts.tip_money.currency	string	The currency.
Amount	order.net_amounts.service_charge_money.amount	integer	The amount.
Currency	order.net_amounts.service_charge_money.currency	string	The currency.

Retrieve subscription

Operation ID:

SubscriptionRetrieve

Retrieves a subscription.

Parameters

Name	Key	Required	Type	Description
Subscription ID	subscription_id	True	string	The identifier of the subscription.

Returns

Name	Path	Type	Description
ID	subscription.id	string	The unique, Square-issued identifier.
Location ID	subscription.location_id	string	The identifier of the location.
Plan ID	subscription.plan_id	string	The ID of the associated subscription plan.
Customer ID	subscription.customer_id	string	The ID of this object representing the customer.
Start Date	subscription.start_date	string	The start date of the subscription, in YYYY-MM-DD format.
Charged Through Date	subscription.charged_through_date	string	The date up to which the customer is invoiced for the subscription, in YYYY-MM-DD format.
Status	subscription.status	string	The current verification status of this object.
Invoice IDs	subscription.invoice_ids	array of string
Amount	subscription.price_override_money.amount	integer	The amount.
Currency	subscription.price_override_money.currency	string	The currency.
Created At	subscription.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Paid Until Date	subscription.paid_until_date	string	The date paid until.
Timezone	subscription.timezone	string	The time zone used to interpret calendar dates. When an invoice is created, this field is set to the timezone specified for the seller location. The value cannot be changed.
Name	subscription.source.name	string	The name.

Search catalog objects

Operation ID:

CatalogSearch

Searches for CatalogObject of any type by matching supported search attribute values, excluding custom attribute values on items or item variations, against one or more of the specified query filters.

Parameters

Name	Key	Required	Type	Description
Object Types	object_types		array of string
Attribute Name	attribute_name		string	The name of the attribute to be searched.
Attribute Prefix	attribute_prefix		string	The desired prefix of the search attribute value.
Limit	limit		integer	A limit on the number of results to be returned in a single page. The limit is advisory - the implementation may return more or fewer results. If the supplied limit is negative, zero, or is higher than the maximum limit of 1,000, it will be ignored.

Returns

Name	Path	Type	Description
Objects	objects	array of object
Type	objects.type	string	The type of this object.
ID	objects.id	string	The unique, Square-issued identifier.
Updated At	objects.updated_at	string	Last modification timestamp in RFC 3339 format
Version	objects.version	integer	The current version of the object.
Is Deleted	objects.is_deleted	boolean	If true, the object has been deleted from the database. Must be false for new objects being inserted. When deleted, the updated_at field will equal the deletion time.
Present at All Locations	objects.present_at_all_locations	boolean	If true, this object is present at all locations (including future locations), except where specified in the absent_at_location_ids field. If false, this object is not present at any locations (including future locations), except where specified in the present_at_location_ids field. If not specified, defaults to true.
Name	objects.item_data.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.
Description	objects.item_data.title	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.
Category ID	objects.item_data.category_id	string	The ID of the item's category, if any.
Product Type	objects.item_data.product_type	string	The product types query expression to return items or item variations having the specified product types.
Tax IDs	objects.item_data.tax_ids	array of string
Variations	objects.item_data.variations	array of object
Type	objects.item_data.variations.type	string	The type of this object. Each object type has expected properties expressed in a structured format within its corresponding *_data field below.
ID	objects.item_data.variations.id	string	An identifier to reference this object.
Updated At	objects.item_data.variations.updated_at	string	Last modification timestamp in RFC 3339 format
Version	objects.item_data.variations.version	integer	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.
Is Deleted	objects.item_data.variations.is_deleted	boolean	If true, the object has been deleted from the database. Must be false for new objects being inserted. When deleted, the updated_at field will equal the deletion time.
Present At All Locations	objects.item_data.variations.present_at_all_locations	boolean	A list of locations where the object is present, even if present_at_all_locations is false. This can include locations that are deactivated.
Item ID	objects.item_data.variations.item_variation_data.item_id	string	The ID of the object with this item variation.
Name	objects.item_data.variations.item_variation_data.name	string	This item's name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.
Ordinal	objects.item_data.variations.item_variation_data.ordinal	integer	The order in which this item variation should be displayed. This value is read-only.
Amount	objects.item_data.variations.item_variation_data.price_money.amount	integer	The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case.
Currency	objects.item_data.variations.item_variation_data.price_money.currency	string	The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.
Pricing Type	objects.item_data.variations.item_variation_data.pricing_type	string	Indicates whether the item variation's price is fixed or determined at the time of sale.
Visibility	objects.item_data.visibility	string	The visibility.

Search customers

Operation ID:

CustomerSearch

Searches the customer profiles associated with a Square account using a supported query filter. Calling SearchCustomers without any explicit query filter returns all customer profiles ordered alphabetically based on given_name and family_name.

Parameters

Name	Key	Required	Type	Description
Fuzzy	fuzzy		string	Use the fuzzy filter to select customers whose attributes match the specified query in a fuzzy manner. When the fuzzy option is used, search queries are tokenized, and then each query token must be matched somewhere in the searched attribute. For single token queries, this is effectively the same behavior as a partial match operation.
Values	values		array of string
Rule	rule		string	Indicates whether a customer profile matching the filter criteria should be included in the result or excluded from the result.
Start At	start_at		string	A datetime value in RFC 3339 format indicating when the time range starts.
End At	end_at		string	A datetime value in RFC 3339 format indicating when the time range ends.
All	all		array of string
Field	field		string	Use one or more customer attributes as the sort key to sort searched customer profiles.
Order	order		string	Indicates the order in which results should be sorted based on the sort field value. Strings use standard alphabetic comparison to determine order.
Limit	limit		integer	A limit on the number of results to be returned in a single page. The limit is advisory - the implementation may return more or fewer results. If the supplied limit is negative, zero, or is higher than the maximum limit of 1,000, it will be ignored.

Returns

Name	Path	Type	Description
Customers	customers	array of object
ID	customers.id	string	The unique, Square-issued identifier.
Created At	customers.created_at	string	The event time in ISO 8601 format.
Updated At	customers.updated_at	string	Last modification timestamp in RFC 3339 format
Given Name	customers.given_name	string	The given (i.e., first) name associated with the customer profile.
Family Name	customers.family_name	string	The family (i.e., last) name associated with the customer profile.
Email Address	customers.email_address	string	The email address associated with the customer profile.
Address Line 1	customers.address.address_line_1	string	The first line of the address.
Address Line 2	customers.address.address_line_2	string	The second line of the address, if any.
Locality	customers.address.locality	string	The city or town of the address.
Administrative District Level 1	customers.address.administrative_district_level_1	string	A civil entity within the address's country. In the US, this is the state.
Postal Code	customers.address.postal_code	string	The address's postal code.
Country	customers.address.country	string	The address's country, in ISO 3166-1-alpha-2 format.
Phone Number	customers.phone_number	string	The 11-digit phone number associated with the customer profile.
Reference ID	customers.reference_id	string	An optional second ID used to associate the customer profile with an entity in another system.
Email Unsubscribed	customers.preferences.email_unsubscribed	boolean	Indicates whether the customer has unsubscribed from marketing campaign emails. A value of true means that the customer chose to opt out of email marketing from the current Square seller or from all Square sellers. This value is read-only from the Customers API.
Creation Source	customers.creation_source	string	A creation source represents the method used to create the customer profile.
Group IDs	customers.group_ids	array of string
Segment IDs	customers.segment_ids	array of string
Version	customers.version	integer	The current version of the object.
Note	customers.note	string	A custom note associated with the customer profile.
Cursor	cursor	string	Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query.

Search invoices

Operation ID:

InvoiceSearch

Searches for invoices from a location specified in the filter.

Parameters

Name	Key	Required	Type	Description
Location IDs	location_ids		array of string
Customer IDs	customer_ids		array of string
Field	field		string	Use one or more customer attributes as the sort key to sort searched customer profiles.
Order	order		string	Indicates the order in which results should be sorted based on the sort field value. Strings use standard alphabetic comparison to determine order.
Limit	limit		integer	The maximum number of invoices to return (200 is the maximum limit). If not provided, the server uses a default limit of 100 invoices.

Returns

Name	Path	Type	Description
Invoices	invoices	array of object
ID	invoices.id	string	The unique, Square-issued identifier.
Version	invoices.version	integer	The current version of the object.
Location ID	invoices.location_id	string	The identifier for the location.
Order ID	invoices.order_id	string	The ID of the order.
Payment Requests	invoices.payment_requests	array of object
UID	invoices.payment_requests.uid	string	The Square-generated ID of the payment request in an invoice.
Request Type	invoices.payment_requests.request_type	string	Identifies the payment request type. This type defines how the payment request amount is determined.
Due Date	invoices.payment_requests.due_date	string	The due date (in the invoice's time zone) for the payment request, in YYYY-MM-DD format.
Tipping Enabled	invoices.payment_requests.tipping_enabled	boolean	If set to true, the Square-hosted invoice page (the public_url field of the invoice) provides a place for the customer to pay a tip.
reminders	invoices.payment_requests.reminders	array of object	Reminders
UID	invoices.payment_requests.reminders.uid	string	A Square-assigned ID that uniquely identifies the reminder within the InvoicePaymentRequest.
Relative Scheduled Days	invoices.payment_requests.reminders.relative_scheduled_days	integer	The number of days before (a negative number) or after (a positive number) the payment request due_date when the reminder is sent.
Message	invoices.payment_requests.reminders.message	string	The reminder message.
Status	invoices.payment_requests.reminders.status	string	The status of the reminder.
Amount	invoices.payment_requests.computed_amount_money.amount	integer	The amount.
Currency	invoices.payment_requests.computed_amount_money.currency	string	The currency.
Amount	invoices.payment_requests.total_completed_amount_money.amount	integer	The amount.
Currency	invoices.payment_requests.total_completed_amount_money.currency	string	The currency.
Automatic Payment Source	invoices.payment_requests.automatic_payment_source	string	The payment method for an automatic payment.
Percentage Requested	invoices.payment_requests.percentage_requested	string	Specifies the amount for the payment request in percentage.
Card ID	invoices.payment_requests.card_id	string	The ID of the credit or debit card on file to charge for the payment request.
Invoice Number	invoices.invoice_number	string	A user-friendly invoice number.
Title	invoices.title	string	The title of the invoice.
Description	invoices.description	string	The description.
Scheduled At	invoices.scheduled_at	string	The timestamp when the invoice is scheduled for processing, in RFC 3339 format. After the invoice is published, Square processes the invoice on the specified date, according to the delivery method and payment request settings.
Status	invoices.status	string	The current verification status of this object.
Timezone	invoices.timezone	string	The time zone used to interpret calendar dates on the invoice, such as due_date. When an invoice is created, this field is set to the timezone specified for the seller location. The value cannot be changed.
Created At	invoices.created_at	string	The event time in ISO 8601 format.
Updated At	invoices.updated_at	string	Last modification timestamp in RFC 3339 format
Customer ID	invoices.primary_recipient.customer_id	string	The ID of a customer to be associated with the card.
Given Name	invoices.primary_recipient.given_name	string	The recipient's given (that is, first) name.
Family Name	invoices.primary_recipient.family_name	string	The recipient's family (that is, last) name.
Email Address	invoices.primary_recipient.email_address	string	The recipient's email address.
Phone Number	invoices.primary_recipient.phone_number	string	The recipient's phone number.
Card	invoices.accepted_payment_methods.card	boolean	Indicates whether credit card or debit card payments are accepted.
Square Gift Card	invoices.accepted_payment_methods.square_gift_card	boolean	Indicates whether Square gift card payments are accepted.
Bank Account	invoices.accepted_payment_methods.bank_account	boolean	Indicates whether bank transfer payments are accepted.
Custom Fields	invoices.custom_fields	array of object
Label	invoices.custom_fields.label	string	The label or title of the custom field.
Value	invoices.custom_fields.value	string	The text of the custom field.
Placement	invoices.custom_fields.placement	string	The location of the custom field on the invoice
Delivery Method	invoices.delivery_method	string	The delivery method that Square uses to send the invoice, reminders, and receipts to the customer.
Sale or Service Date	invoices.sale_or_service_date	string	The date of the sale or the date that the service is rendered, in YYYY-MM-DD format. This field can be used to specify a past or future date which is displayed on the invoice.
Public URL	invoices.public_url	string	The URL of the Square-hosted invoice page. After you publish the invoice using the PublishInvoice endpoint, Square hosts the invoice page and returns the page URL in the response.
Amount	invoices.next_payment_amount_money.amount	integer	The amount.
Currency	invoices.next_payment_amount_money.currency	string	The currency.
Cursor	cursor	string	Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query.

Search orders

Operation ID:

OrderSearch

Search all orders for one or more locations. Orders include all sales, returns, and exchanges regardless of how or when they entered the Square ecosystem (such as Point of Sale, Invoices, and Connect APIs).

Parameters

Name	Key	Required	Type	Description
Return Entries	return_entries		boolean	A Boolean that controls the format of the search results. If true, SearchOrders returns OrderEntry objects. If false, SearchOrders returns complete order objects.
Limit	limit		integer	A limit on the number of results to be returned in a single page. The limit is advisory - the implementation may return more or fewer results. If the supplied limit is negative, zero, or is higher than the maximum limit of 1,000, it will be ignored.
Location IDs	location_ids		array of string
Start At	start_at		string	A datetime value in RFC 3339 format indicating when the time range starts.
End At	end_at		string	A datetime value in RFC 3339 format indicating when the time range ends.
States	states		array of string
Sort Field	sort_field		string	The field to sort by.
Sort Order	sort_order		string	The chronological order in which results are returned.

Returns

Name	Path	Type	Description
Order Entries	order_entries	array of object
Order ID	order_entries.order_id	string	The ID of the order.
Location ID	order_entries.location_id	string	The identifier for the location.
Version	order_entries.version	integer	The current version of the object.
Cursor	cursor	string	Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query.

Search subscriptions

Operation ID:

SubscriptionSearch

Searches for subscriptions. Results are ordered chronologically by subscription creation date. If the request specifies more than one location ID, the endpoint orders the result by location ID, and then by creation date within each location. If no locations are given in the query, all locations are searched.

Parameters

Name	Key	Required	Type	Description
Location IDs	location_ids		array of string
Customer IDs	customer_ids		array of string
Source Names	source_names		array of string

Returns

Name	Path	Type	Description
Subscriptions	subscriptions	array of object
ID	subscriptions.id	string	The unique, Square-issued identifier.
Location ID	subscriptions.location_id	string	The identifier for the location.
Plan ID	subscriptions.plan_id	string	The ID of the associated subscription plan
Customer ID	subscriptions.customer_id	string	The Square-assigned ID of the customer that is associated with the account.
Start Date	subscriptions.start_date	string	The start date of the subscription, in YYYY-MM-DD format.
Canceled Date	subscriptions.canceled_date	string	The subscription cancellation date, in YYYY-MM-DD format.
Charged Through Date	subscriptions.charged_through_date	string	The date up to which the customer is invoiced for the subscription, in YYYY-MM-DD format.
Status	subscriptions.status	string	The current verification status of this object.
Created At	subscriptions.created_at	string	The event time in ISO 8601 format.
Card ID	subscriptions.card_id	string	The ID of the customer card that is charged for the subscription.
Paid Until Date	subscriptions.paid_until_date	string	The date paid until.
Timezone	subscriptions.timezone	string	The time zone used to interpret calendar dates on the invoice, such as due_date. When an invoice is created, this field is set to the timezone specified for the seller location. The value cannot be changed.
Name	subscriptions.source.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.
Tax Percentage	subscriptions.tax_percentage	string	The tax amount applied when billing the subscription.
Amount	subscriptions.price_override_money.amount	integer	The amount.
Currency	subscriptions.price_override_money.currency	string	The currency.
Version	subscriptions.version	integer	The current version of the object.
Invoice IDs	subscriptions.invoice_ids	array of string

Search terminal checkouts

Operation ID:

TerminalSearchCheckouts

Retrieves a filtered list of Terminal checkout requests created by the account making the request.

Parameters

Name	Key	Required	Type	Description
Limit	limit		integer	A limit on the number of results to be returned in a single page. The limit is advisory - the implementation may return more or fewer results. If the supplied limit is negative, zero, or is higher than the maximum limit of 1,000, it will be ignored.
Status	status		string	The current status.

Returns

Name	Path	Type	Description
Checkouts	checkouts	array of object
ID	checkouts.id	string	The unique, Square-issued identifier.
Amount	checkouts.amount_money.amount	integer	The amount.
Currency	checkouts.amount_money.currency	string	The currency.
Reference ID	checkouts.reference_id	string	An optional second ID used to associate the customer profile with an entity in another system.
Note	checkouts.note	string	A custom note associated with the customer profile.
Device ID	checkouts.device_options.device_id	string	The unique ID of the device intended for this TerminalCheckout.
Allow Tipping	checkouts.device_options.tip_settings.allow_tipping	boolean	Indicates whether tipping is enabled for this checkout. Defaults to false.
Skip Receipt Screen	checkouts.device_options.skip_receipt_screen	boolean	Instructs the device to skip the receipt screen. Defaults to false.
Status	checkouts.status	string	The current verification status of this object.
Payment IDs	checkouts.payment_ids	array of string
Created At	checkouts.created_at	string	The event time in ISO 8601 format.
Updated At	checkouts.updated_at	string	Last modification timestamp in RFC 3339 format
App ID	checkouts.app_id	string	The ID of the application that created the checkout.
Deadline Duration	checkouts.deadline_duration	string	An RFC 3339 duration, after which the checkout is automatically canceled. A TerminalCheckout that is PENDING is automatically CANCELED and has a cancellation reason of TIMED_OUT. Default: 5 minutes from creation
Cursor	cursor	string	Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query.

Search terminal refunds

Operation ID:

TerminalSearchRefunds

Retrieves a filtered list of Interac Terminal refund requests created by the seller making the request.

Parameters

Name	Key	Required	Type	Description
Limit	limit		integer	A limit on the number of results to be returned in a single page. The limit is advisory - the implementation may return more or fewer results. If the supplied limit is negative, zero, or is higher than the maximum limit of 1,000, it will be ignored.
Status	status		string	The current status.

Returns

Name	Path	Type	Description
Refunds	refunds	array of object
ID	refunds.id	string	The unique, Square-issued identifier.
Refund ID	refunds.refund_id	string	The unique ID for this refund, generated by Square.
Payment ID	refunds.payment_id	string	The ID of the payment.
Amount	refunds.amount_money.amount	integer	The amount.
Currency	refunds.amount_money.currency	string	The currency.
Reason	refunds.reason	string	The dispute reason why the cardholder initiated the dispute with their bank.
Device ID	refunds.device_id	string	The unique id of the device that used this code. Populated when the device is paired.
Deadline Duration	refunds.deadline_duration	string	An RFC 3339 duration, after which the checkout is automatically canceled. A TerminalCheckout that is PENDING is automatically CANCELED and has a cancellation reason of TIMED_OUT. Default: 5 minutes from creation
Status	refunds.status	string	The current verification status of this object.
Created At	refunds.created_at	string	The event time in ISO 8601 format.
Updated At	refunds.updated_at	string	Last modification timestamp in RFC 3339 format
App ID	refunds.app_id	string	The ID of the application that created the checkout.
Card Brand	refunds.card.card_brand	string	The card's brand.
Last 4	refunds.card.last_4	string	The last 4 digits of the card number.
Expiration Month	refunds.card.exp_month	integer	The expiration month of the associated card as an integer between 1 and 12.
Expiration Year	refunds.card.exp_year	integer	The four-digit year of the card's expiration date.
Fingerprint	refunds.card.fingerprint	string	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
Card Type	refunds.card.card_type	string	The type of the card.
BIN	refunds.card.bin	string	The first six digits of the card number, known as the Bank Identification Number (BIN).
Order ID	refunds.order_id	string	The ID of the order.
Location ID	refunds.location_id	string	The identifier for the location.

Submit evidence

Operation ID:

EvidenceSubmit

Submits evidence to the cardholder's bank. Before submitting evidence, Square compiles all available evidence. This includes evidence uploaded using the CreateDisputeEvidenceFile and CreateDisputeEvidenceText endpoints and evidence automatically provided by Square, when available.

Parameters

Name	Key	Required	Type	Description
Dispute ID	dispute_id	True	string	The identifier of the dispute.

Returns

Name	Path	Type	Description
ID	dispute.id	string	The unique, Square-issued identifier.
Amount	dispute.amount_money.amount	integer	The amount.
Currency	dispute.amount_money.currency	string	The currency.
Reason	dispute.reason	string	The reason for this object.
State	dispute.state	string	The current state.
Due At	dispute.due_at	string	The time when the next action is due, in RFC 3339 format.
Disputed Payments	dispute.disputed_payments	array of object
Payment ID	dispute.disputed_payments.payment_id	string	Square-generated unique ID of the payment.
Card Brand	dispute.card_brand	string	The card's brand.
Created At	dispute.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	dispute.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Brand Dispute ID	dispute.brand_dispute_id	string	The ID of the dispute in the card brand system, generated by the card brand.

Update customer

Operation ID:

CustomerUpdate

Updates a customer profile. To change an attribute, specify the new value. To remove an attribute, specify the value as an empty string or empty object.

Parameters

Name	Key	Required	Type	Description
Customer ID	customer_id	True	string	The identifier of the customer.

Returns

Name	Path	Type	Description
ID	customer.id	string	The unique, Square-issued identifier.
Created At	customer.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	customer.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Given Name	customer.given_name	string	The given (i.e., first) name associated with the customer profile.
Family Name	customer.family_name	string	The family (i.e., last) name associated with the customer profile.
Email Address	customer.email_address	string	The email address associated with the customer profile.
Address Line 1	customer.address.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.
Address Line 2	customer.address.address_line_2	string	The second line of the address, if any.
Locality	customer.address.locality	string	The city or town of the address.
Administrative District Level 1	customer.address.administrative_district_level_1	string	A civil entity within the address's country. In the US, this is the state.
Postal Code	customer.address.postal_code	string	The address's postal code.
Country	customer.address.country	string	The address's country, in ISO 3166-1-alpha-2 format.
Reference ID	customer.reference_id	string	An optional user-defined reference ID.
Note	customer.note	string	A custom note associated with the customer profile.
Email Unsubscribed	customer.preferences.email_unsubscribed	boolean	Indicates whether the customer has unsubscribed from marketing campaign emails. A value of true means that the customer chose to opt out of email marketing from the current Square seller or from all Square sellers.
Creation Source	customer.creation_source	string	A creation source represents the method used to create the customer profile.
Version	customer.version	integer	The current version of this object.

Update customer group

Operation ID:

CustomerGroupUpdate

Updates a customer group.

Parameters

Name	Key	Required	Type	Description
Group ID	group_id	True	string	The identifier of the group.
Name	name		string	The name of the object.

Returns

Name	Path	Type	Description
ID	group.id	string	The unique, Square-issued identifier.
Name	group.name	string	The name of the object.
Created At	group.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	group.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.

Update invoice

Operation ID:

InvoiceUpdate

Updates an invoice by modifying fields, clearing fields, or both.

Parameters

Name	Key	Required	Type	Description
Invoice ID	invoice_id	True	string	The identifier of the invoice.
Idempotency Key	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).
UID	uid		string	The Square-generated ID.
Tipping Enabled	tipping_enabled		boolean	If set to true, provides a place for the customer to pay a tip.
Fields to Clear	fields_to_clear		array of string

Returns

Name	Path	Type	Description
ID	invoice.id	string	The unique, Square-issued identifier.
Version	invoice.version	integer	The current version of this object.
Location ID	invoice.location_id	string	The identifier of the location.
Order ID	invoice.order_id	string	The ID of the order.
Payment Requests	invoice.payment_requests	array of object
UID	invoice.payment_requests.uid	string	The Square-generated ID.
Request Type	invoice.payment_requests.request_type	string	Identifies the payment request type. This type defines how the payment request amount is determined.
Due Date	invoice.payment_requests.due_date	string	The due date for the payment request, in YYYY-MM-DD format.
Tipping Enabled	invoice.payment_requests.tipping_enabled	boolean	If set to true, provides a place for the customer to pay a tip.
Amount	invoice.payment_requests.computed_amount_money.amount	integer	The amount.
Currency	invoice.payment_requests.computed_amount_money.currency	string	The currency.
Amount	invoice.payment_requests.total_completed_amount_money.amount	integer	The amount.
Currency	invoice.payment_requests.total_completed_amount_money.currency	string	The currency.
Automatic Payment Source	invoice.payment_requests.automatic_payment_source	string	The payment method for an automatic payment.
Invoice Number	invoice.invoice_number	string	A user-friendly invoice number. The value is unique within a location. If not provided when creating an invoice, Square assigns a value.
Title	invoice.title	string	The title.
Description	invoice.description	string	The description.
Scheduled At	invoice.scheduled_at	string	The timestamp when the processing is scheduled, in RFC 3339 format.
Status	invoice.status	string	The current verification status of this object.
Timezone	invoice.timezone	string	The time zone used to interpret calendar dates. When an invoice is created, this field is set to the timezone specified for the seller location. The value cannot be changed.
Created At	invoice.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	invoice.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Customer ID	invoice.primary_recipient.customer_id	string	The ID of the customer associated with the order.
Given Name	invoice.primary_recipient.given_name	string	The recipient's given (that is, first) name.
Family Name	invoice.primary_recipient.family_name	string	The recipient's family (that is, last) name.
Email Address	invoice.primary_recipient.email_address	string	The recipient's email address.
Phone Number	invoice.primary_recipient.phone_number	string	The recipient's phone number.
Amount	invoice.next_payment_amount_money.amount	integer	The amount.
Currency	invoice.next_payment_amount_money.currency	string	The currency.
Card	invoice.accepted_payment_methods.card	boolean	Indicates whether credit card or debit card payments are accepted.
Square Gift Card	invoice.accepted_payment_methods.square_gift_card	boolean	Indicates whether Square gift card payments are accepted.
Bank Account	invoice.accepted_payment_methods.bank_account	boolean	Indicates whether bank transfer payments are accepted.
Custom Fields	invoice.custom_fields	array of object
Label	invoice.custom_fields.label	string	The label or title of the custom field.
Value	invoice.custom_fields.value	string	The text of the custom field.
Placement	invoice.custom_fields.placement	string	The location of the custom field on the invoice.
Delivery Method	invoice.delivery_method	string	The delivery method that Square uses to send the invoice, reminders, and receipts to the customer. After the invoice is published, Square processes the invoice based on the delivery method and payment request settings, either immediately or on the scheduled_at date, if specified.
Sale or Service Date	invoice.sale_or_service_date	string	The date of the sale or the date that the service is rendered, in YYYY-MM-DD format. This field can be used to specify a past or future date which is displayed on the invoice.

Update item modifier lists

Operation ID:

CatalogUpdateModifier

Updates the CatalogModifierList objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item.

Parameters

Name	Key	Required	Type	Description
Item IDs	item_ids		array of string
Modifier Lists to Enable	modifier_lists_to_enable		array of string
Modifier Lists to Disable	modifier_lists_to_disable		array of string

Returns

Name	Path	Type	Description
Updated At	updated_at	string	The database timestamp of this update in RFC 3339 format.

Update item taxes

Operation ID:

CatalogUpdateTaxes

Updates the CatalogTax objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item.

Parameters

Name	Key	Required	Type	Description
Item IDs	item_ids		array of string
Taxes to Enable	taxes_to_enable		array of string
Taxes to Disable	taxes_to_disable		array of string

Returns

Name	Path	Type	Description
Updated At	updated_at	string	The database timestamp of this update in RFC 3339 format.

Update order (Beta)

Operation ID:

OrderUpdate

Updates an open order by adding, replacing, or deleting fields. Orders with a COMPLETED or CANCELED state cannot be updated.

Parameters

Name	Key	Required	Type	Description
Order ID	order_id	True	string	The identifier of the order.
Idempotency Key	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).
Version	version		integer	The current version of this object.
UID	uid		string	The Square-generated ID.
Quantity	quantity		string	The number of items affected by the physical count as a decimal string. The number can support up to 5 digits after the decimal point.
Name	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.
Amount	amount		integer	The amount.
Currency	currency		string	The currency.
Fields to Clear	fields_to_clear		array of string

Returns

Name	Path	Type	Description
Version	order.version	integer	The current version of this object.
Currency	order.total_money.currency	string	The currency.
Amount	order.total_money.amount	integer	The amount.
Name	order.source.name	string	The name.
Line Items	order.line_items	array of object
Currency	order.line_items.total_tax_money.currency	string	The currency.
Amount	order.line_items.total_tax_money.amount	integer	The amount.
Amount	order.line_items.total_money.amount	integer	The amount.
Currency	order.line_items.total_money.currency	string	The currency.
Amount	order.line_items.gross_sales_money.amount	integer	The amount.
Currency	order.line_items.gross_sales_money.currency	string	The currency.
Amount	order.line_items.base_price_money.amount	integer	The amount.
Currency	order.line_items.base_price_money.currency	string	The currency.
Quantity	order.line_items.quantity	string	The number of items affected by the physical count as a decimal string. The number can support up to 5 digits after the decimal point.
Currency	order.line_items.total_discount_money.currency	string	The currency.
Amount	order.line_items.total_discount_money.amount	integer	The amount.
Name	order.line_items.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.
UID	order.line_items.uid	string	The Square-generated ID.
Amount	order.line_items.variation_total_price_money.amount	integer	The amount.
Currency	order.line_items.variation_total_price_money.currency	string	The currency.
State	order.state	string	The current state.
Amount	order.total_service_charge_money.amount	integer	The amount.
Currency	order.total_service_charge_money.currency	string	The currency.
ID	order.id	string	The unique, Square-issued identifier.
Location ID	order.location_id	string	The identifier of the location.
Amount	order.total_tax_money.amount	integer	The amount.
Currency	order.total_tax_money.currency	string	The currency.
Created At	order.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Amount	order.total_discount_money.amount	integer	The amount.
Currency	order.total_discount_money.currency	string	The currency.
Currency	order.net_amounts.service_charge_money.currency	string	The currency.
Amount	order.net_amounts.service_charge_money.amount	integer	The amount.
Amount	order.net_amounts.total_money.amount	integer	The amount.
Currency	order.net_amounts.total_money.currency	string	The currency.
Currency	order.net_amounts.discount_money.currency	string	The currency.
Amount	order.net_amounts.discount_money.amount	integer	The amount.
Currency	order.net_amounts.tax_money.currency	string	The currency.
Amount	order.net_amounts.tax_money.amount	integer	The amount.
Updated At	order.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.

Update payment

Operation ID:

PaymentUpdate

Updates a payment with the APPROVED status. You can update the amount_money and tip_money using this endpoint.

Parameters

Name	Key	Required	Type	Description
Payment ID	payment_id	True	string	The identifier of the payment.
Idempotency Key	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).
Amount	amount		integer	The amount.
Currency	currency		string	The currency.
Amount	amount		integer	The amount.
Currency	currency		string	The currency.
Version Token	version_token		string	This opaque token identifies a specific version of the object.

Returns

Name	Path	Type	Description
ID	payment.id	string	The unique, Square-issued identifier.
Created At	payment.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Updated At	payment.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Amount	payment.amount_money.amount	integer	The amount.
Currency	payment.amount_money.currency	string	The currency.
Amount	payment.tip_money.amount	integer	The amount.
Currency	payment.tip_money.currency	string	The currency.
Status	payment.status	string	The current verification status of this object.
Delay Duration	payment.delay_duration	string	The duration of time after the payment's creation when Square automatically applies the delay_action to the payment. This automatic delay_action applies only to payments that do not reach a terminal state (COMPLETED, CANCELED, or FAILED) before the delay_duration time period. This field is specified as a time duration, in RFC 3339 format.
Source Type	payment.source_type	string	The source type for this payment. Current values include CARD, BANK_ACCOUNT, WALLET, CASH, or EXTERNAL.
Status	payment.card_details.status	string	The current status.
Card Brand	payment.card_details.card.card_brand	string	The card's brand.
Last 4	payment.card_details.card.last_4	string	The last 4 digits of the card number.
Exp Month	payment.card_details.card.exp_month	integer	The expiration month of the associated card as an integer between 1 and 12.
Exp Year	payment.card_details.card.exp_year	integer	The four-digit year of the card's expiration date.
Fingerprint	payment.card_details.card.fingerprint	string	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
Card Type	payment.card_details.card.card_type	string	The type of the card.
Prepaid Type	payment.card_details.card.prepaid_type	string	Indicates whether the Card is prepaid or not.
BIN	payment.card_details.card.bin	string	The first six digits of the card number, known as the Bank Identification Number (BIN).
Entry Method	payment.card_details.entry_method	string	The method used to enter the card's details for the payment. The method can be KEYED, SWIPED, EMV, ON_FILE, or CONTACTLESS.
CVV Status	payment.card_details.cvv_status	string	The status code returned from the Card Verification Value (CVV) check. The code can be CVV_ACCEPTED, CVV_REJECTED, or CVV_NOT_CHECKED.
AVS Status	payment.card_details.avs_status	string	The status code returned from the Address Verification System (AVS) check. The code can be AVS_ACCEPTED, AVS_REJECTED, or AVS_NOT_CHECKED.
Auth Result Code	payment.card_details.auth_result_code	string	The status code returned by the card issuer that describes the payment's authorization status.
Statement Description	payment.card_details.statement_description	string	The statement description sent to the card networks.
Authorized At	payment.card_details.card_payment_timeline.authorized_at	string	The timestamp when the payment was authorized, in RFC 3339 format.
Location ID	payment.location_id	string	The identifier of the location.
Order ID	payment.order_id	string	The ID of the order.
Created At	payment.risk_evaluation.created_at	string	The timestamp when created, in RFC 3339 format.
Risk Level	payment.risk_evaluation.risk_level	string	The risk level associated with the payment.
Note	payment.note	string	A custom note associated with the customer profile.
Customer ID	payment.customer_id	string	The ID of this object representing the customer.
Amount	payment.total_money.amount	integer	The amount.
Currency	payment.total_money.currency	string	The currency.
Amount	payment.approved_money.amount	integer	The amount.
Currency	payment.approved_money.currency	string	The currency.
Capabilities	payment.capabilities	array of string
Receipt Number	payment.receipt_number	string	The payment's receipt number. The field is missing if a payment is canceled.
Delay Action	payment.delay_action	string	The action to be applied to the payment when the delay_duration has elapsed.
Delayed Until	payment.delayed_until	string	The read-only timestamp of when the delay_action is automatically applied, in RFC 3339 format.
Square Product	payment.application_details.square_product	string	The Square product, such as Square Point of Sale (POS), Square Invoices, or Square Virtual Terminal.
Application ID	payment.application_details.application_id	string	Read-only Square ID assigned to the application.
Version Token	payment.version_token	string	This opaque token identifies a specific version of the object.

Update subscription

Operation ID:

SubscriptionUpdate

Updates a subscription. You can set, modify, and clear the subscription field values.

Parameters

Name	Key	Required	Type	Description
Subscription ID	subscription_id	True	string	The identifier of the subscription.
Version	version		integer	The current version of this object.
Tax Percentage	tax_percentage		string	The tax amount applied when billing the subscription.
Amount	amount		integer	The amount.
Currency	currency		string	The currency.

Returns

Name	Path	Type	Description
ID	subscription.id	string	The unique, Square-issued identifier.
Location ID	subscription.location_id	string	The identifier of the location.
Plan ID	subscription.plan_id	string	The ID of the associated subscription plan.
Customer ID	subscription.customer_id	string	The ID of this object representing the customer.
Status	subscription.status	string	The current verification status of this object.
Amount	subscription.price_override_money.amount	integer	The amount.
Currency	subscription.price_override_money.currency	string	The currency.
Version	subscription.version	integer	The current version of this object.
Created At	subscription.created_at	string	The timestamp specifying the creation time of this object, in RFC 3339 format.
Timezone	subscription.timezone	string	The time zone used to interpret calendar dates. When an invoice is created, this field is set to the timezone specified for the seller location. The value cannot be changed.
Name	subscription.source.name	string	The name.

Upsert catalog object

Operation ID:

CatalogUpsert

Creates or updates the target CatalogObject.

Parameters

Name	Key	Required	Type	Description
Idempotency Key	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).
ID	id		string	The unique, Square-issued identifier.
Type	type		string	The type of this object.
Abbreviation	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.
Description	title		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.
Name	name		string	The name.
ID	id		string	An identifier to reference this object in the catalog.
Type	type		string	The type of this object.
Item ID	item_id		string	The ID of the CatalogItem associated with this item variation.
Name	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.
Pricing Type	pricing_type		string	Indicates whether the item variation's price is fixed or determined at the time of sale.
Amount	amount		integer	The amount.
Currency	currency		string	The currency.

Returns

Name	Path	Type	Description
Type	catalog_object.type	string	The type of this object.
ID	catalog_object.id	string	The unique, Square-issued identifier.
Updated At	catalog_object.updated_at	string	The timestamp specifying the most recent update time of this object, in RFC 3339 format.
Version	catalog_object.version	integer	The current version of this object.
Is Deleted	catalog_object.is_deleted	boolean	If true, the object has been deleted from the database. Must be false for new objects being inserted. When deleted, the updated_at field will equal the deletion time.
present_at_all_locations	catalog_object.present_at_all_locations	boolean	If true, this object is present at all locations (including future locations), except where specified in the absent_at_location_ids field. If false, this object is not present at any locations (including future locations), except where specified in the present_at_location_ids field. If not specified, defaults to true.
Name	catalog_object.item_data.name	string	The name.
Description	catalog_object.item_data.title	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.
Abbreviation	catalog_object.item_data.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.
Variations	catalog_object.item_data.variations	array of object
Type	catalog_object.item_data.variations.type	string	The type of this object.
ID	catalog_object.item_data.variations.id	string	An identifier to reference this object in the catalog.
Updated At	catalog_object.item_data.variations.updated_at	string	Last modification timestamp in RFC 3339 format.
Version	catalog_object.item_data.variations.version	integer	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.
Is Deleted	catalog_object.item_data.variations.is_deleted	boolean	If true, the object has been deleted from the database. Must be false for new objects being inserted. When deleted, the updated_at field will equal the deletion time.
Present at All Locations	catalog_object.item_data.variations.present_at_all_locations	boolean	If true, this object is present at all locations (including future locations), except where specified in the absent_at_location_ids field. If false, this object is not present at any locations (including future locations), except where specified in the present_at_location_ids field. If not specified, defaults to true.
Item ID	catalog_object.item_data.variations.item_variation_data.item_id	string	The ID of the CatalogItem associated with this item variation.
Name	catalog_object.item_data.variations.item_variation_data.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	catalog_object.item_data.variations.item_variation_data.ordinal	integer	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.
Pricing Type	catalog_object.item_data.variations.item_variation_data.pricing_type	string	Indicates whether the item variation's price is fixed or determined at the time of sale.
Stockable	catalog_object.item_data.variations.item_variation_data.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.
Amount	catalog_object.item_data.variations.item_variation_data.price_money.amount	integer	The amount.
Currency	catalog_object.item_data.variations.item_variation_data.price_money.currency	string	The currency.
Product Type	catalog_object.item_data.product_type	string	The product type of the item. May not be changed once an item has been created.
ID Mappings	id_mappings	array of object
Client Object ID	id_mappings.client_object_id	string	The client-supplied temporary #-prefixed ID for a new CatalogObject.
Object ID	id_mappings.object_id	string	The permanent ID created by the server.

Definitions

object

This is the type 'object'.