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 |
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 |
Name | Calls | Renewal Period |
---|---|---|
API calls per connection | 100 | 60 seconds |
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. |
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. |
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
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. |
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 |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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
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. |
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 |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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 |
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
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
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
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
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. |
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. |
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. |
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. |
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 |
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. |
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. |
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. |
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 |
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 |
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. |
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. |
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. |
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. |
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. |
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. |
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 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. |
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. |
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. |
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. |
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
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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 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. |
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 |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
This is the type 'object'.