Partilhar via


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

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

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

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

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

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

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

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

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

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)

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

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

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

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

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

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

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

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)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)

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

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

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

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'.