Connect v1 API Reference

Square Connect API Conventions

Common conventions for Connect API endpoints are described here.

Client libraries

Square provides client libraries for Connect V1 and V2 in a variety of programming languages. See Client libraries for a full list.

Swagger specification

Version 1 and 2 of the Connect API is defined with the Swagger specification. The definition is available on Github. You can use this definition to simplify certain development tasks, such as by generating custom client libraries.

See Generating client libraries and other tools with Swagger for more information.

Running Postman

Postman is an app for easy RESTful API exploration. Use our "Postman Collection" to try Square's Connect endpoints. Read our blog post on setting up Postman and configuring it with your API credentials.

Click Run in Postman below to explore our V1 and V2 API Collection.

Endpoint paths

Connect API endpoints are hosted from the base URL https://connect.squareup.com. For example, the List Payments endpoint's full path is https://connect.squareup.com/v1/{location_id}/payments.

Most endpoint paths include a location_id parameter that indicates which of a business' locations your application is acting on behalf of. You can get a business' location IDs with the List Locations endpoint.

API versions

An endpoint's API version is included in its path. Bug fixes and minor feature additions might be made to an endpoint's behavior without advancing its version number. This can include adding optional parameters or response fields. To prevent future compatibility issues, your application should be prepared to receive response fields beyond those currently returned by a given endpoint.

Functionality is never removed from a particular version of an endpoint, nor do field names or types change.

Endpoint names and return values

An endpoint's name indicates the type of data it handles and the action it performs on that data. The most common actions are:

ActionHTTP MethodDescription
CreatePOSTCreates and persists an entity of the corresponding type.
ListGETReturns summary information for all entities that match query parameters you provide. To get comprehensive information for a particular entity, first get the entity's id with the appropriate List endpoint, then provide the id to the corresponding Retrieve endpoint.
RetrieveGETProvides comprehensive information for the single entity that matches the identifier you provide.
UpdatePUTModifies the existing entity that matches the identifier you provide.
DeleteDELETEDeletes the existing entity that matches the identifier you provide. Deleted entities cannot be retrieved or undeleted.

For example, the List Payments endpoint returns an array of processed payments, and the Create Item endpoint creates and persists an item.

Request and response headers

Requests to Connect API endpoints must include the following HTTP headers:

Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

In the place of YOUR_ACCESS_TOKEN, provide either your application's personal access token (available from the application dashboard) or an access token you generated with the OAuth API.

POST and PUT requests must include one additional header:

Content-Type: application/json

By default, all endpoint responses provide data as JSON in the response body and include a Content-Type: application/json header.

Providing parameters

The way you provide parameters to a Connect API request depends on the HTTP method of the request.

GET and DELETE requests

For GET and DELETE requests, you provide parameters in a query string you append to your request's URL. For example, you provide the order parameter to the List Payments endpoint like so:

https://connect.squareup.com/v1/LOCATION_ID/payments?order=DESC

Values for query parameters must be URL-escaped. For example, to provide the value 2013-01-15T00:00:00+02:00 as the begin_time parameter of the List Payments endpoint, you specify the following:

https://connect.squareup.com/v1/LOCATION_ID/payments?begin_time=2013-01-15T00%3A00%3A00%2B02%3A00

POST and PUT requests

For POST and PUT requests, you instead provide parameters as JSON in the body of your request.

For example, the body of a request to the Update Category endpoint looks like this:

{
  "name" : "Sandwiches"
}

Working with monetary amounts

All monetary amounts in the Connect API are represented by the Money object, which has the following structure:

{
  "amount": 400,
  "currency_code": "USD"
}

The amount field is always in the smallest denomination of the currency indicated by currency_code. For example:

  • When currency_code is USD (US dollars), amount is in cents. The object shown above represents $4.00.
  • When currency_code is JPY (Japanese yen), amount is in yen.

The currency_code field is in ISO 4217 format.

Working with dates

All representations of dates are strings in ISO 8601 format.

You can provide date strings that are either UTC (for example, 2013-01-15T00:00:00Z) or offset from UTC to indicate time zone (for example, 2013-01-15T00:00:00-08:00 for eight hours behind UTC). If you provide offset dates, be sure to account for daylight saving time correctly, if applicable.

Date strings returned by the Connect API are always UTC.

Date ranges

Certain List endpoints (such as List Payments) accept an optional date range with the begin_time and end_time parameters. They also accept an optional order parameter, which indicates whether results are returned in chronological or reverse-chronological order.

Regardless of order, begin_time is the earlier date and end_time is the later date.

When order is ASC (chronological), begin_time is inclusive and end_time is exclusive. This is the default behavior for all List endpoints.

When order is DESC (reverse-chronological), begin_time is exclusive and end_time is inclusive.

See the reference for a particular List endpoint to see if that endpoint accepts begin_time and end_time parameters.

Paginating results

List endpoints might paginate the results they return. This means that instead of returning all results in a single response, these endpoints might return some of the results, along with a response header that links to the next set of results. This header has the following format:

Link:<https://connect.squareup.com/v1/LOCATION_ID/payments?batch_token=BATCH_TOKEN>;rel='next'

Send a followup request (including all usual headers) to the next URL to fetch the next set of results. Repeat this process until you receive a response without a next URL.

Note: The batch_token parameter included in the next URL is a short-lived token that should be used only once to fetch the next set of results for a particular query. Do not persist or reuse this value.

Batching requests

The Connect API provides a Submit Batch endpoint, which lets you batch multiple Connect API requests into a single request. The endpoint performs all requests included in a batch and returns an array containing each request's response.

Handling duplicate results

List endpoints might return duplicate results. Use the id attribute of the result objects to identify any such duplicates.

Handling the enum value OTHER

Some Connect API enums (such as BankAccount.Type) include the value OTHER. If you retrieve an object (such as a BankAccount) that currently has the value OTHER for one of its fields, that field might have a different value if you retrieve the object again at a later date, when an appropriate value has been added to the enum.

Enum values besides OTHER never change retroactively.

Replacing application credentials

You can replace your application's personal access token or application secret from the application dashboard.

  • Click Replace Token next to the Personal Access Token field to generate a new token for your application.
  • Click Replace Secret next to the Application Secret field to generate a new secret for your application.

Replacing an application credential immediately invalidates the previous credential. Make sure you update your application accordingly.

Rate limiting

If Connect API endpoints receive too many requests associated with the same application or access token in a short time window, they might respond with a 429 Too Many Requests error. If this occurs, try your request again at a later time.

Handling errors

Connect API endpoints use HTTP protocol status codes to indicate errors. Error code values range from 400 to 599.

All Connect API error responses provide a JSON object with the following fields:

NameTypeDescription
typestring

The type of error that occurred. This value does not change based on the locale of the request.

messagestring

A human-readable message describing the error. This message is always in English. You should not rely on the value of the message for a particular error, because it might change in the future.

The following are the possible error types that correspond to each HTTP error code. Your application should be ready to handle any of these errors from any Connect API endpoint.

Bad Request (400)

TypeDescription
bad_request.missing_parameterA required parameter was missing from the request.
bad_request.invalid_parameterThe request included an invalid parameter.
bad_requestThe request was otherwise malformed.

Unauthorized (401)

TypeDescription
service.not_authorizedYour application is not authorized to make this request.
oauth.revokedYour application's access token was revoked.
oauth.expiredYour application's access token has expired.

Forbidden (403)

TypeDescription
forbiddenThe requesting application does not have permission to access the resource, typically because the OAuth token's permission scope is insufficient.

Not Found (404)

TypeDescription
not_foundThe resource specified in the request wasn't found.

Unprocessable Entity (422)

TypeDescription
unprocessable_entityThe request is well formed but has semantic errors. For example, this error occurs when you attempt to create an item variation with the same SKU as an existing variation.

Too Many Requests (429)

TypeDescription
too_many_requestsThe Connect API has received too many requests associated with the same access token or application in too short a time span. Try your request again later.

Internal Server Error (500)

TypeDescription
internal_server_errorSquare encountered an unexpected error processing the request.

Service Unavailable (503)

TypeDescription
service_unavailableThe Connect API service is currently unavailable.

Business Management

Business Management Overview

The Connect API provides endpoints for managing a merchant's business organization, including its locations, employees, and timecards.

See Structure of a Square Business for descriptions of the entities included in a Square business.

Getting a business' locations

You can get information about all of a business' locations with the List Locations endpoint.

This information includes each location's id, which you include in the path of most other requests you make to Connect API endpoints.

Adding employees to a business

Use the Create Employee endpoint to add an employee to a merchant's business. In your request, you provide a name and an optional role that specifies which actions the employee can and can't perform.

Employees created with the Connect API have an initial status of INACTIVE. Inactive employees cannot sign in to Square Point of Sale until the merchant activates the employee from their Square Dashboard. You cannot change an employee's status with the Connect API.

Use the List Employees endpoint to see all of a business' employees.

Important: You cannot delete an employee entity after you create it. If an employee leaves the organization, you can set the corresponding entity's status to INACTIVE with the Update Employee endpoint.

Managing employee roles and permissions

Merchants can define any number of roles that they then assign to their employees. These roles specify the permissions that are granted to employees with the role. For example, an employee with a "Shift Manager" role might be able to issue refunds in Square Point of Sale, whereas an employee with a "Clerk" role might not.

Use the Create Role endpoint to create a new role for an business. In your request, you specify the permissions to grant employees with the role. See EmployeeRole.Permission for descriptions of possible permissions.

You can assign a role to an employee with the Update Employee endpoint. An employee can have only one role at a time.

If an employee has no role, they have none of the permissions associated with roles. All employees can accept payments with Square Point of Sale.

Managing timecards

Merchants can use timecards to track when their employees clock in and out.

Timecard format

In the Connect API, a Timecard object corresponds to exactly one shift for a given employee, bounded by its clockin_time and clockout_time fields.

An employee is considered clocked in if they have a timecard that doesn't have a clockout_time set.

The values of these fields are set by timecard events that are created for the timecard. Each event has one of the following types:

TypeDescription
API_CREATEThe timecard was created by a request to the Create Timecard endpoint.
API_EDITThe timecard was edited by a request to the Update Timecard endpoint.
API_DELETEThe timecard was deleted by a request to the Delete Timecard endpoint.
REGISTER_CLOCKINThe employee clocked in via Square Point of Sale.
REGISTER_CLOCKOUTThe employee clocked out via Square Point of Sale.
DASHBOARD_SUPERVISOR_CLOSEA supervisor clocked out the employee from the merchant dashboard.
DASHBOARD_EDITA supervisor manually edited the timecard from the merchant dashboard.
DASHBOARD_DELETEA supervisor deleted the timecard from the merchant dashboard.

All timecard events created with the Connect API have an event type that begins with API.

You can get a timecard's complete event history with the List Timecard Events endpoint.

Clocking in

Your application can clock in an employee with the Create Timecard endpoint. The endpoint automatically creates an API_CREATE event for the new timecard. The clockin_time field of the timecard is set to the current time unless you provide a different value.

If an employee is currently clocked in (i.e., they have a timecard that doesn't have a clockout_time set), you cannot clock them in again.

Clocking out and other actions

Your application can use the Update Timecard endpoint to set or change the clockin_time or clockout_time of a timecard. The endpoint automatically creates an API_EDIT event for the timecard.

You can clock out an employee by setting the clockout_time for the employee's currently active timecard.

Importing timecards

You can use the Create Timecard endpoint to import timecards from another system. Just specify the clockin_time and clockout_time of the timecard you're importing in your request.

Handling deleted timecards

Timecards can be deleted from the merchant dashboard, or with the Delete Timecard endpoint. Unlike deleted items, deleted timecards are still accessible from Connect API endpoints. The deleted field of the Timecard object indicates whether the timecard has been deleted. You cannot modify a deleted timecard.

By default, deleted timecards appear alongside valid timecards in results returned by the List Timecards endpoint. Include the deleted query parameter in your request to filter timecards by the value of their deleted field.

Retrieve Business

GET /v1/me

Provides a business' account information, such as its name and associated email address.

Required permissions: MERCHANT_PROFILE_READ

Return Value

A Merchant object describing the business.

Example Request

https://connect.squareup.com/v1/me

Example Response Body

{
  "id": "18YC4JBH91E1H",
  "name": "Dave Davis",
  "email": "dave@example.com",
  "country_code": "US",
  "language_code": "en-US",
  "account_type": "BUSINESS"
}

List Locations

GET /v1/me/locations

Provides details for a business' locations, including their IDs.

The account_capabilities array returned in each Merchant object indicates which account capabilities the location has enabled. For example, if this array does not include the value CREDIT_CARD_PROCESSING, the location cannot currently process credit cards with Square.

Required permissions: MERCHANT_PROFILE_READ

Return Value

An array of Merchant objects containing profile information for the business' locations.

Example Request

https://connect.squareup.com/v1/me/locations

Example Response Body

[
  {
    "id": "JGHJ0343",
    "name": "Dave Davis",
    "email": "dave@example.com",
    "country_code": "US",
    "language_code": "en-US",
    "currency_code": "USD",
    "business_name": "Dave's Milkshakes",
    "business_address": {
      "address_line_1": "1455 Market St",
      "locality": "San Francisco",
      "administrative_district_level_1": "CA",
      "postal_code": "94103"
    },
    "business_phone": {
      "calling_code": "+1",
      "number": "4155551234"
    },
    "business_type": "restaurants",
    "shipping_address": {
      "address_line_1": "1455 Market St",
      "locality": "San Francisco",
      "administrative_district_level_1": "CA",
      "postal_code": "94103"
    },
    "account_type": "LOCATION",
    "location_details": {
      "nickname": "Milkshakes"
    },
    "market_url": "https://mkt.com/squared",
    "account_capabilities": ["CREDIT_CARD_PROCESSING"]
  }
]

Create Employee

POST /v1/me/employees

Creates an employee for a business.

Required permissions: EMPLOYEES_WRITE

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
first_namestring

The employee's first name.

last_namestring

The employee's last name.

role_ids (optional)string[]

The ids of the employee's associated roles. Currently, you can specify only one or zero roles per employee.

Default value: []

email (optional)string

An optional email address to associate with the employee.

Note that you cannot edit an existing employee's email address with the Connect API. You can only set its initial value when creating an employee.

Return Value

An Employee object that represents the created employee.

Example Request Body

{
  "first_name": "Amelia",
  "last_name": "Earhart",
  "role_ids": ["a1265191-2105-7cd8-7c8539267308"],
  "email": "amelia@example.com"
}

Example Response Body

{
  "id": "1f6d3d87-5d70-1893-17061da6f6a2",
  "first_name": "Amelia",
  "last_name": "Earhart",
  "status": "INACTIVE",
  "role_ids": ["a1265191-2105-7cd8-7c8539267308"],
  "email": "amelia@example.com",
  "created_at": "1928-04-16T18:45:00Z",
  "updated_at": "1928-04-16T18:45:00Z"
}

List Employees

GET /v1/me/employees

Provides summary information for all of a business' employees.

You can filter the results returned by this endpoint by exactly one of the following fields:

  • created_at
  • updated_at

Attempting to filter by more than one of the above fields produces an error.

You can additionally filter results by status and external_id.

No matter which filters you use, results are sorted by their created_at field.

Required permissions: EMPLOYEES_READ

Request Parameters

For GET and DELETE endpoints, you provide request parameters in a query string appended to the request URL.

NameTypeDescription
order (optional)ListOrder

The order in which employees are listed in the response, based on their created_at field.

Default value: ASC

begin_updated_at (optional)string

If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format.

end_updated_at (optional)string

If filtering results by there updated_at field, the end of the requested reporting period, in ISO 8601 format.

begin_created_at (optional)string

If filtering results by their created_at field, the beginning of the requested reporting period, in ISO 8601 format.

end_created_at (optional)string

If filtering results by their created_at field, the end of the requested reporting period, in ISO 8601 format.

status (optional)Employee.Status

If provided, the endpoint returns only employee entities with the specified status (ACTIVE or INACTIVE).

external_id (optional)string

If provided, the endpoint returns only employee entities with the specified external_id.

limit (optional)number

The maximum number of employee entities to return in a single response. This value cannot exceed 200.

This value is always an integer.

Default value: 100

Return Value

An array of zero or more Employee objects.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/v1/me/employees?status=ACTIVE&external_id=CANARY

Example Response Body

[
  {
    "authorized_location_ids": [ "JGHJ0343" ],
    "id": "1f6d3d87-5d70-1893-17061da6f6a2",
    "first_name": "Amelia",
    "last_name": "Earhart",
    "status": "ACTIVE",
    "external_id": "CANARY",
    "role_ids": ["a1265191-2105-7cd8-7c8539267308"],
    "email": "amelia@example.com",
    "created_at": "1928-04-16T18:45:00Z",
    "updated_at": "1928-04-16T18:45:00Z"
  }
]

Retrieve Employee

GET /v1/me/employees/{employee_id}

Provides the details for a single employee.

Required permissions: EMPLOYEES_READ

Path Parameters

NameTypeDescription
employee_idstring

The employee's ID.

Return Value

An Employee object that describes the requested employee.

Example Request

https://connect.squareup.com/v1/me/employees/EMPLOYEE_ID

Example Response Body

{
  "id": "1f6d3d87-5d70-1893-17061da6f6a2",
  "first_name": "Amelia",
  "last_name": "Earhart",
  "status": "ACTIVE",
  "external_id": "CANARY",
  "role_ids": ["a1265191-2105-7cd8-7c8539267308"],
  "email": "amelia@example.com",
  "created_at": "1928-04-16T18:45:00Z",
  "updated_at": "1928-04-16T18:45:00Z"
}

Update Employee

PUT /v1/me/employees/{employee_id}

Modifies the details of an employee.

Required permissions: EMPLOYEES_WRITE

Path Parameters

NameTypeDescription
employee_idstring

The ID of the employee to modify.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
first_name (optional)string

The employee's first name.

last_name (optional)string

The employee's last name.

role_ids (optional)string[]

The employee's associated roles. Currently, you can specify only one or zero roles per employee.

Return Value

An Employee object that represents the updated employee.

Example Request Body

{
  "first_name": "Amelia",
  "last_name": "Earhart",
  "role_ids": ["a1265191-2105-7cd8-7c8539267308"]
}

Example Response Body

{
  "id": "1f6d3d87-5d70-1893-17061da6f6a2",
  "first_name": "Amelia",
  "last_name": "Earhart",
  "status": "INACTIVE",
  "external_id": "CANARY",
  "role_ids": ["a1265191-2105-7cd8-7c8539267308"],
  "email": "amelia@example.com",
  "created_at": "1928-04-16T18:45:00Z",
  "updated_at": "1937-07-24T18:45:00Z"
}

Create Role

POST /v1/me/roles

Creates an employee role you can then assign to employees.

Required permissions: EMPLOYEES_WRITE

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
namestring

The role's name.

permissionsEmployeeRole.Permission[]

The role's permissions.

is_owner (optional)boolean

If true, employees with this role have all permissions, regardless of the values indicated in permissions.

Default value: false

Return Value

An EmployeeRole object that represents the created role.

Example Request Body

{
  "name": "Manager",
  "permissions": [
    "REGISTER_APPLY_RESTRICTED_DISCOUNTS",
    "REGISTER_ISSUE_REFUNDS",
    "REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE"
  ],
  "is_owner": false
}

Example Response Body

{
  "id": "3ee15b98-521c-6534-c889103c210e",
  "name": "Manager",
  "permissions": [
    "REGISTER_APPLY_RESTRICTED_DISCOUNTS",
    "REGISTER_ISSUE_REFUNDS",
    "REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE"
  ],
  "is_owner": false,
  "created_at": "2014-07-16T18:45:00Z",
  "updated_at": "2014-07-16T18:45:00Z"
}

List Roles

GET /v1/me/roles

Provides summary information for all of a business' employee roles.

Required permissions: EMPLOYEES_READ

Request Parameters

For GET and DELETE endpoints, you provide request parameters in a query string appended to the request URL.

NameTypeDescription
order (optional)ListOrder

The order in which roles are listed in the response.

Default value: ASC

limit (optional)number

The maximum number of employee entities to return in a single response. This value cannot exceed 200.

This value is always an integer.

Default value: 100

Return Value

An array of zero or more EmployeeRole objects.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/v1/me/roles

Example Response Body

[
  {
    "id": "3ee15b98-521c-6534-c889103c210e",
    "name": "Manager",
    "permissions": [
      "REGISTER_APPLY_RESTRICTED_DISCOUNTS",
      "REGISTER_ISSUE_REFUNDS",
      "REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE"
    ],
    "is_owner": false,
    "created_at": "2014-07-16T18:45:00Z",
    "updated_at": "2014-07-16T18:45:00Z"
  }
]

Retrieve Role

GET /v1/me/roles/{role_id}

Provides the details for a single employee role.

Required permissions: EMPLOYEES_READ

Path Parameters

NameTypeDescription
role_idstring

The role's ID.

Return Value

An EmployeeRole object that describes the requested role.

Example Request

https://connect.squareup.com/v1/me/roles/ROLE_ID

Example Response Body

{
  "id": "3ee15b98-521c-6534-c889103c210e",
  "name": "Manager",
  "permissions": [
    "REGISTER_APPLY_RESTRICTED_DISCOUNTS",
    "REGISTER_ISSUE_REFUNDS",
    "REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE"
  ],
  "is_owner": false,
  "created_at": "2014-07-16T18:45:00Z",
  "updated_at": "2014-07-16T18:45:00Z"
}

Update Role

PUT /v1/me/roles/{role_id}

Modifies the details of an employee role.

Required permissions: EMPLOYEES_WRITE

Path Parameters

NameTypeDescription
role_idstring

The ID of the role to modify.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
name (optional)string

The role's name.

permissions (optional)EmployeeRole.Permission[]

The role's permissions.

is_owner (optional)boolean

If true, employees with this role have all permissions, regardless of the values indicated in permissions.

Return Value

An EmployeeRole object that represents the updated role.

Example Request Body

{
  "name": "Manager",
  "permissions": [
    "REGISTER_APPLY_RESTRICTED_DISCOUNTS",
    "REGISTER_ISSUE_REFUNDS",
    "REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE"
  ],
  "is_owner": false
}

Example Response Body

{
  "id": "3ee15b98-521c-6534-c889103c210e",
  "name": "Manager",
  "permissions": [
    "REGISTER_APPLY_RESTRICTED_DISCOUNTS",
    "REGISTER_ISSUE_REFUNDS",
    "REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE"
  ],
  "is_owner": false,
  "created_at": "2014-07-16T18:45:00Z",
  "updated_at": "2014-07-19T18:45:00Z"
}

Create Timecard

POST /v1/me/timecards

Creates a timecard for an employee. Each timecard corresponds to a single shift.

This endpoint automatically creates an API_CREATE event for the new timecard.

Required permissions: TIMECARDS_WRITE

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
employee_idstring

The employee to create a timecard for.

clockin_time (optional)string

The clock-in time for the timecard, in ISO 8601 format.

Default value: The current time.

clockout_time (optional)string

The clock-out time for the timecard, in ISO 8601 format. Provide this value only if importing timecard information from another system.

clockin_location_id (optional)string

The ID of the location the employee clocked in from, if any.

clockout_location_id (optional)string

The ID of the location the employee clocked out from. Provide this value only if importing timecard information from another system.

If you provide this value, you must also provide a value for clockout_time.

Return Value

A Timecard object that represents the created timecard.

Example Request Body

{
  "employee_id": "1f6d3d87-5d70-1893-17061da6f6a2"
}

Example Response Body

{
  "id": "9265a379-a044-4036-82d10a6a7dd1",
  "deleted": false,
  "clockin_time": "2014-11-15T09:00:00Z",
  "employee_id": "1f6d3d87-5d70-1893-17061da6f6a2",
  "created_at": "2014-11-15T09:00:00Z",
  "updated_at": "2014-11-15T09:00:00Z"
}

List Timecards

GET /v1/me/timecards

Provides summary information for all of a business' employee timecards.

You can filter the results returned by this endpoint by exactly one of the following fields:

  • clockin_time
  • clockout_time
  • updated_at

Attempting to filter by more than one of these fields produces an error.

You can also filter results by employee_id, and by whether or not timecards have been deleted.

No matter which filters you use, results are sorted by their created_at field.

Required permissions: TIMECARDS_READ

Request Parameters

For GET and DELETE endpoints, you provide request parameters in a query string appended to the request URL.

NameTypeDescription
order (optional)ListOrder

The order in which timecards are listed in the response, based on their created_at field.

Default value: ASC

employee_id (optional)string

If provided, the endpoint returns only timecards for the employee with the specified ID.

begin_clockin_time (optional)string

If filtering results by their clockin_time field, the beginning of the requested reporting period, in ISO 8601 format.

end_clockin_time (optional)string

If filtering results by their clockin_time field, the end of the requested reporting period, in ISO 8601 format.

begin_clockout_time (optional)string

If filtering results by their clockout_time field, the beginning of the requested reporting period, in ISO 8601 format.

end_clockout_time (optional)string

If filtering results by their clockout_time field, the end of the requested reporting period, in ISO 8601 format.

begin_updated_at (optional)string

If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format.

end_updated_at (optional)string

If filtering results by their updated_at field, the end of the requested reporting period, in ISO 8601 format.

deleted (optional)boolean

If true, only deleted timecards are returned. If false, only valid timecards are returned.

If you don't provide this parameter, both valid and deleted timecards are returned.

limit (optional)number

The maximum number of timecards to return in a single response. This value cannot exceed 200.

This value is always an integer.

Return Value

An array of zero or more Timecard objects.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/v1/me/timecards

Example Response Body

[
  {
    "id": "9265a379-a044-4036-82d10a6a7dd1",
    "deleted": false,
    "clockin_time": "2014-11-15T09:00:00Z",
    "clockout_time": "2014-11-15T17:00:00Z",
    "employee_id": "1f6d3d87-5d70-1893-17061da6f6a2",
    "created_at": "2014-11-15T09:00:00Z",
    "updated_at": "2014-11-15T17:00:00Z"
  }
]

Retrieve Timecard

GET /v1/me/timecards/{timecard_id}

Provides the details for a single timecard.

Required permissions: TIMECARDS_READ

Path Parameters

NameTypeDescription
timecard_idstring

The timecard's ID.

Return Value

A Timecard object that describes the requested timecard.

Example Request

https://connect.squareup.com/v1/me/timecards/TIMECARD_ID

Example Response Body

{
  "id": "9265a379-a044-4036-82d10a6a7dd1",
  "deleted": false,
  "clockin_time": "2014-11-15T09:00:00Z",
  "clockout_time": "2014-11-15T17:00:00Z",
  "employee_id": "1f6d3d87-5d70-1893-17061da6f6a2",
  "created_at": "2014-11-15T09:00:00Z",
  "updated_at": "2014-11-15T17:00:00Z"
}

Update Timecard

PUT /v1/me/timecards/{timecard_id}

Modifies a timecard's details. This creates an API_EDIT event for the timecard. You can view a timecard's event history with the List Timecard Events endpoint.

Required permissions: TIMECARDS_WRITE

Path Parameters

NameTypeDescription
timecard_idstring

The ID of the timecard to modify.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
clockin_time (optional)string

The clock-in time for the timecard, in ISO 8601 format.

clockout_time (optional)string

The clock-out time for the timecard, in ISO 8601 format.

clockin_location_id (optional)string

The ID of the location the employee clocked in from, if any.

clockout_location_id (optional)string

The ID of the location the employee clocked out from, if any.

Return Value

A Timecard object that represents the updated timecard.

Example Request Body

{
  "clockin_time": "2014-11-15T09:00:00Z",
  "clockout_time": "2014-11-15T16:00:00Z"
}

Example Response Body

{
  "id": "9265a379-a044-4036-82d10a6a7dd1",
  "deleted": false,
  "clockin_time": "2014-11-15T09:00:00Z",
  "clockout_time": "2014-11-15T16:00:00Z",
  "employee_id": "1f6d3d87-5d70-1893-17061da6f6a2",
  "created_at": "2014-11-15T09:00:00Z",
  "updated_at": "2014-11-15T18:22:00Z"
}

Delete Timecard

DELETE /v1/me/timecards/{timecard_id}

Deletes a timecard. Deleted timecards are still accessible from Connect API endpoints, but the value of their deleted field is set to true. See Handling deleted timecards for more information.

Required permissions: TIMECARDS_WRITE

Path Parameters

NameTypeDescription
timecard_idstring

The ID of the timecard to delete.

Return Value

If the request succeeds, the endpoint returns a 200 status code and an empty JSON object, {}.

Example Request

https://connect.squareup.com/v1/me/timecards/TIMECARD_ID

List Timecard Events

GET /v1/me/timecards/{timecard_id}/events

Provides summary information for all events associated with a particular timecard.

Required permissions: TIMECARDS_READ

Path Parameters

NameTypeDescription
timecard_idstring

The ID of the timecard to list events for.

Return Value

An array of zero or more TimecardEvent objects.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/v1/me/timecards/TIMECARD_ID/events

Example Response Body

[
  {
    "id": "4ac40454-5f6d-9c6d-d5061364",
    "event_type": "API_CREATE",
    "clockin_time": "2014-11-15T09:00:00Z",
    "created_at": "2014-11-15T09:00:00Z"
  },
  {
    "id": "f6921655-ea25-4410-30d6e368",
    "event_type": "API_EDIT",
    "clockin_time": "2014-11-15T09:00:00Z",
    "clockout_time": "2014-11-15T17:00:00Z",
    "created_at": "2014-11-15T17:00:00Z"
  }
]

List Cash Drawer Shifts

GET /v1/{location_id}/cash-drawer-shifts

Provides the details for all of a location's cash drawer shifts during a date range. The date range you specify cannot exceed 90 days.

CashDrawerShift objects returned by this endpoint do not include the events field, which lists the events that occurred during the shift. To get a particular shift's events, use the Retrieve Cash Drawer Shift endpoint.

Required permissions: PAYMENTS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to list cash drawer shifts for.

Request Parameters

For GET and DELETE endpoints, you provide request parameters in a query string appended to the request URL.

NameTypeDescription
begin_timestring

The beginning of the requested reporting period, in ISO 8601 format.

Default value: The current time minus 90 days.

end_timestring

The beginning of the requested reporting period, in ISO 8601 format.

Default value: The current time.

order (optional)ListOrder

The order in which cash drawer shifts are listed in the response, based on their created_at field.

Default value: ASC

Return Value

An array of zero or more CashDrawerShift objects.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/cash-drawer-shifts

Example Response Body

[
  {
     "id" : "D2F60C1C-FF18-43AA-B56B-FFC130B0C866",
     "opened_at" : "2015-04-13T11:06:44Z",
     "ended_at" : "2015-04-13T17:03:30Z",
     "opening_employee_id": "1f6d3d87-5d70-1893-17061da6f6a2",
     "ending_employee_id": "1f6d3d87-5d70-1893-17061da6f6a2",
     "employee_ids" : ["1f6d3d87-5d70-1893-17061da6f6a2"],
     "starting_cash_money" : {
       "amount" : 0,
       "currency_code" : "USD"
     },
     "cash_payment_money" : {
       "amount" : 1000,
       "currency_code" : "USD"
     },
     "cash_refunds_money" : {
       "amount" : -400,
       "currency_code" : "USD"
     },
     "cash_paid_in_money" : {
       "amount" : 0,
       "currency_code" : "USD"
     },
     "cash_paid_out_money" : {
       "amount" : 0,
       "currency_code" : "USD"
     },
     "expected_cash_money" : {
       "amount" : 600,
       "currency_code" : "USD"
     },
     "cash_drawer_state" : "ENDED",
     "device" : {
       "name" : "Front of store"
     },
     "description" : ""
   }
]

Retrieve Cash Drawer Shift

GET /v1/{location_id}/cash-drawer-shifts/{shift_id}

Provides the details for a single cash drawer shift, including all events that occurred during the shift.

Required permissions: PAYMENTS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the cash drawer shift's associated location.

shift_idstring

The shift's ID.

Return Value

A CashDrawerShift object that describes the requested shift.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/cash-drawer-shifts/D2F60C1C-FF18-43AA-B56B-FFC130B0C866

Example Response Body

{
  "id" : "D2F60C1C-FF18-43AA-B56B-FFC130B0C866",
  "opened_at" : "2015-04-13T11:06:44Z",
  "ended_at" : "2015-04-13T17:03:30Z",
  "opening_employee_id": "1f6d3d87-5d70-1893-17061da6f6a2",
  "ending_employee_id": "1f6d3d87-5d70-1893-17061da6f6a2",
  "employee_ids" : ["1f6d3d87-5d70-1893-17061da6f6a2"],
  "starting_cash_money" : {
    "amount" : 0,
    "currency_code" : "USD"
  },
  "cash_payment_money" : {
    "amount" : 1000,
    "currency_code" : "USD"
  },
  "cash_refunds_money" : {
    "amount" : -400,
    "currency_code" : "USD"
  },
  "cash_paid_in_money" : {
    "amount" : 0,
    "currency_code" : "USD"
  },
  "cash_paid_out_money" : {
    "amount" : 0,
    "currency_code" : "USD"
  },
  "expected_cash_money" : {
    "amount" : 600,
    "currency_code" : "USD"
  },
  "events" : [
    {
      "created_at" : "2015-04-13T12:09:44Z",
      "event_type" : "CASH_TENDER_PAYMENT",
      "id" : "B2262B6F-8A4E-4856-88B4-CAFBC271A3DE",
      "employee_id" : "1f6d3d87-5d70-1893-17061da6f6a2",
      "event_money" : {
        "amount" : 1000,
        "currency_code" : "USD"
      },
      "description" : ""
    },
    {
      "created_at" : "2015-04-13T15:11:44Z",
      "event_type" : "CASH_TENDER_REFUND",
      "id" : "95A471EE-84D2-502B-4ED1-FBCBFDD847E5",
      "employee_id" : "1f6d3d87-5d70-1893-17061da6f6a2",
      "event_money" : {
        "amount" : -400,
        "currency_code" : "USD"
      },
      "description" : ""
    }
  ],
  "cash_drawer_state" : "ENDED",
  "device" : {
    "name" : "Front of store"
  },
  "description" : ""
}

Transaction Management

Transaction Management Overview

With these endpoints, Square merchants can:

  • Retrieve reports of completed payments, refunds, and settlements
  • Issue refunds for completed payments
  • Manage orders from a merchant's online store

Entities related to transaction management are described here.

Payments

A payment represents a paid transaction between a Square merchant and a customer. Payment details are usually available from Connect API endpoints within a few minutes after the transaction completes.

Each Payment object returned by the Connect API has several fields that end in _money. These fields describe the various amounts of money that contribute to the payment's total:

FieldDescription
inclusive_tax_moneyThe total of all inclusive taxes applied to the payment.
additive_tax_moneyThe total of all additive taxes applied to the payment.
tax_moneyThe sum of inclusive_tax_money and additive_tax_money.
tip_moneyThe total of all tips applied to the payment.
discount_moneyThe total of all discounts applied to the payment.
total_collected_moneyThe grand total for the payment (the amount that the buyer actually paid).
processing_fee_moneyThe amount of all Square processing fees applied to the payment.
net_total_moneyThe amount that was (or will be) deposited into the merchant's bank account.
refunded_moneyThe total of all refunds applied to the payment.

Monetary values are positive if they represent an increase in the amount of money the merchant receives (such as tax_money and tip_money). They're negative if they represent a decrease (such as discount_money, processing_fee_money, and refunded_money).

Payment itemizations

Payment objects returned by Connect API endpoints include an itemizations field that lists the items purchased, along with associated fees, modifiers, and discounts. Each itemization has an itemization_type field that indicates which of the following the itemization represents:

  • An item variation from the merchant's item library
  • A custom monetary amount
  • An action performed on a Square gift card, such as activating or reloading it

Like Payment objects, PaymentItemization objects have several fields ending in _money that describe the amounts of money that contribute to their total.

Note that itemization information included in a Payment object reflects details collected at the time of the payment. Details such as the name or price of items might have changed since the payment was processed.

Offline payments

If a merchant processes a payment in Square Point of Sale's offline mode, the payment's details might not be transmitted to Square for up to 72 hours. Offline payments have a created_at value that reflects the time the payment was originally processed, not the time it was subsequently transmitted to Square. Consequently, the List Payments endpoint might list an offline payment chronologically between online payments that you had already seen in a previous request.

Gift card payments

When a customer purchases a Square gift card from a merchant, the merchant receives the full amount of the gift card in the associated payment.

When a customer pays for a purchase with a Square gift card, the merchant receives no funds. Instead, the balance of the gift card is simply reduced. You can identify a gift card payment from its tender field. A Tender object with a type of SQUARE_GIFT_CARD indicates a gift card was used for some or all of the associated payment.

Split tender payments

Square merchants can accept more than one form of tender for a single payment (such as by splitting a bill between a credit card and a gift card). The tender field of the Payment object lists all forms of tender used for the payment.

Split tender payments behave slightly differently from single tender payments:

  • A split tender payment's receipt_url field corresponds only to the first tender listed in the tender field. To get the receipt URLs for the remaining tenders, use the receipt_url fields of the corresponding Tender objects.
  • You cannot issue a partial refund for a split tender payment. You must instead issue a full or partial refund for a particular tender, by providing that tender's id to the Create Refund endpoint. Issuing a full refund for a split tender payment refunds all tenders associated with the payment.

Refunds

Refunds are initiated by a Square merchant and applied to a previously processed payment. Refund details are usually available from Connect API endpoints within a few minutes after the merchant initiates the refund.

Refund objects indicate the payment the refund applies to, the amount of money refunded, and the reason for the refund.

Issuing refunds

You can issue full or partial refunds for completed payments with the Create Refund endpoint. You must issue a refund within 120 days of the associated payment. See this article for more information on refund behavior.

Issuing a refund for a card payment is not reversible. For development purposes, you can create fake cash payments in Square Point of Sale and refund them.

You cannot issue a partial refund for a split tender payment. You must instead issue a partial refund for a particular tender, by providing that tender's id to the Create Refund endpoint. Issuing a full refund for a split tender payment refunds all tenders associated with the payment.

Settlements

A settlement represents a deposit or withdrawal initiated by Square to a merchant's bank account.

Settlement objects returned by the Retrieve Settlement endpoint include an entries field that lists the transactions that contribute to the settlement's total. Most settlement entries correspond to a payment that a merchant processed and is now being paid out for. Settlement entries are also generated for less common events, like refunds, manual adjustments, or chargeback holds. See Settlement.EntryType for descriptions of the different types of settlement entries.

Note that the List Settlements endpoint does not provide entry information.

Square initiates its regular deposits to merchant bank accounts on the schedule indicated on this page. Details for a regular deposit are usually not available from Connect API endpoints before 10 p.m. PST the same day.

Square does not know when an initiated settlement completes, only whether it has failed. A completed settlement is typically reflected in a merchant's bank account within three business days, but in exceptional cases it might take longer.

Orders

Orders from a merchant's online store are initiated by buyers and fulfilled by merchants, typically by shipping purchased items. Order details are usually available from Connect API endpoints within a few minutes after an order is initiated.

The Order objects returned by Connect API endpoints do not include a list of the items purchased. To get the items purchased, provide the payment_id of an Order object to the Retrieve Payment endpoint. The itemizations field of the returned Payment object lists the items purchased.

Order states

Every online store order has one of 6 current states that describe its progress through the completion flow:

  • A PENDING order has recently been created and is in the process of being validated by Square.
  • An OPEN order has been validated by Square and is ready to be fulfilled by the merchant.
  • A COMPLETED order is a previously OPEN order that has been shipped or otherwise fulfilled by the merchant.
  • A CANCELED order is a previously OPEN order that has expired or has otherwise been canceled by the merchant.
  • A REFUNDED order is a previously COMPLETED order that has since been refunded by the merchant.
  • A REJECTED order cannot be processed because it was rejected by Square.

Retrieving orders

Use the List Orders endpoint to retrieve your orders.

Updating an order's state

You can update an order's state with the Update Order endpoint to complete it, cancel it, or refund it.

Note that to COMPLETE or CANCEL an order, its current state must be OPEN. To REFUND an order, its current state must be COMPLETED.

If you REFUND an order, a refund is initiated for the order's associated payment.

List Payments

GET /v1/{location_id}/payments

Provides summary information for all payments taken by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length. See Date ranges for details of inclusive and exclusive dates.

Required permissions: PAYMENTS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to list payments for.

If you specify me, this endpoint returns payments aggregated from all of the business' locations.

Get a business' locations with the List Locations endpoint.

Request Parameters

For GET and DELETE endpoints, you provide request parameters in a query string appended to the request URL.

NameTypeDescription
begin_time (optional)string

The beginning of the requested reporting period, in ISO 8601 format.

If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error.

Default value: The current time minus one year.

end_time (optional)string

The end of the requested reporting period, in ISO 8601 format.

If this value is more than one year greater than begin_time, this endpoint returns an error.

Default value: The current time.

order (optional)ListOrder

The order in which payments are listed in the response.

Default value: ASC

limit (optional)number

The maximum number of payments to return in a single response. This value cannot exceed 200.

This value is always an integer.

Default value: 100

Return Value

An array of zero or more Payment objects.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/payments?begin_time=2013-01-15T00:00:00Z&end_time=2013-01-31T00:00:00Z

Example Response Body

[
  {
    "id": "Jq74mCczmFXk1tC10GB",
    "merchant_id": "JGHJ0343",
    "created_at": "2014-07-07T18:45:00Z",
    "creator_id": "18YC4JBH91E1G",
    "device": {
      "name": "Front of store"
    },
    "payment_url": "https://squareup.com/dashboard/sales/transactions/Jq74mCczmFXk1tC10GB",
    "inclusive_tax_money": {
      "currency_code": "USD",
      "amount": 0
    },
    "additive_tax_money": {
      "currency_code": "USD",
      "amount": 24
    },
    "tax_money": {
      "currency_code": "USD",
      "amount": 24
    },
    "tip_money": {
      "currency_code": "USD",
      "amount": 0
    },
    "discount_money": {
      "currency_code": "USD",
      "amount": -45
    },
    "total_collected_money": {
      "currency_code": "USD",
      "amount": 429
    },
    "processing_fee_money": {
      "currency_code": "USD",
      "amount": -12
    },
    "net_total_money": {
      "currency_code": "USD",
      "amount": 417
    },
    "refunded_money": {
      "currency_code": "USD",
      "amount": 0
    },
    "inclusive_tax": [],
    "additive_tax": [
      {
        "name": "Sales tax",
        "rate": "0.060000",
        "inclusion_type": "ADDITIVE",
        "applied_money": {
          "currency_code": "USD",
          "amount": 24
        }
      }
    ],
    "tender": [
      {
        "type": "CREDIT_CARD",
        "name": "Credit Card",
        "total_money": {
          "currency_code": "USD",
          "amount": 429
        },
        "card_brand": "DISCOVER",
        "pan_suffix": "1117",
        "entry_method": "SWIPED"
      }
    ],
    "refunds": [],
    "itemizations": [
      {
        "name": "Milkshake",
        "quantity": "1.00000000",
        "notes": "Delicious!",
        "item_variation_name": "Small",
        "item_detail": {
          "category_name": "Beverages",
          "sku": "123",
          "item_id": "a1c50178-19ad-4783-aee4-4f2548ca8254",
          "item_variation_id": "8219dd37-666f-4855-be73-b5d28826580b"
        },
        "total_money": {
          "currency_code": "USD",
          "amount": 429
        },
        "single_quantity_money": {
          "currency_code": "USD",
          "amount": 400
        },
        "gross_sales_money": {
          "currency_code": "USD",
          "amount": 450
        },
        "discount_money": {
          "currency_code": "USD",
          "amount": -45
        },
        "net_sales_money": {
          "currency_code": "USD",
          "amount": 405
        },
        "taxes": [
          {
            "name": "Sales tax",
            "rate": "0.060000",
            "inclusion_type": "ADDITIVE",
            "applied_money": {
              "currency_code": "USD",
              "amount": 24
            },
            "fee_id": "19498df7-3fb0-4c96-8b47-860480718abk"
          }
        ],
        "discounts": [
          {
            "name": "Early Bird",
            "applied_money": {
              "currency_code": "USD",
              "amount": -45
            },
            "discount_id": "0f075287-094c-4de7-9e23-cff5d41c910b"
          }
        ],
        "modifiers": [
          {
            "name": "Whipped Cream",
            "applied_money": {
              "currency_code": "USD",
              "amount": 50
            },
            "modifier_option_id": "39059fd0-ae9d-4eb3-b6e8-dd3198f019b8"
          }
        ]
      }
    ]
  }
]

Retrieve Payment

GET /v1/{location_id}/payments/{payment_id}

Provides comprehensive information for a single payment.

Required permissions: PAYMENTS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the payment's associated location.

Get a business' locations with the List Locations endpoint.

payment_idstring

The payment's Square-issued ID. You obtain this value from Payment objects returned by the List Payments endpoint, or Settlement objects returned by the List Settlements endpoint.

Return Value

A Payment object that describes the requested payment.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/payments/Jq74mCczmFXk1tC10GB

Example Response Body

{
  "id": "Jq74mCczmFXk1tC10GB",
  "merchant_id": "JGHJ0343",
  "created_at": "2014-07-07T18:45:00Z",
  "creator_id": "18YC4JBH91E1G",
  "device": {
    "name": "Front of store"
  },
  "payment_url": "https://squareup.com/dashboard/sales/transactions/Jq74mCczmFXk1tC10GB",
  "inclusive_tax_money": {
    "currency_code": "USD",
    "amount": 0
  },
  "additive_tax_money": {
    "currency_code": "USD",
    "amount": 24
  },
  "tax_money": {
    "currency_code": "USD",
    "amount": 24
  },
  "tip_money": {
    "currency_code": "USD",
    "amount": 0
  },
  "discount_money": {
    "currency_code": "USD",
    "amount": -45
  },
  "total_collected_money": {
    "currency_code": "USD",
    "amount": 429
  },
  "processing_fee_money": {
    "currency_code": "USD",
    "amount": -12
  },
  "net_total_money": {
    "currency_code": "USD",
    "amount": 417
  },
  "refunded_money": {
    "currency_code": "USD",
    "amount": 0
  },
  "inclusive_tax": [],
  "additive_tax": [
    {
      "name": "Sales tax",
      "rate": "0.060000",
      "inclusion_type": "ADDITIVE",
      "applied_money": {
        "currency_code": "USD",
        "amount": 24
      }
    }
  ],
  "tender": [
    {
      "type": "CREDIT_CARD",
      "name": "Credit Card",
      "total_money": {
        "currency_code": "USD",
        "amount": 429
      },
      "card_brand": "DISCOVER",
      "pan_suffix": "1117",
      "entry_method": "SWIPED"
    }
  ],
  "refunds": [],
  "itemizations": [
    {
      "name": "Milkshake",
      "quantity": "1.00000000",
      "notes": "Delicious!",
      "item_variation_name": "Small",
      "item_detail": {
        "category_name": "Beverages",
        "sku": "123",
        "item_id": "a1c50178-19ad-4783-aee4-4f2548ca8254",
        "item_variation_id": "8219dd37-666f-4855-be73-b5d28826580b"
      },
      "total_money": {
        "currency_code": "USD",
        "amount": 429
      },
      "single_quantity_money": {
        "currency_code": "USD",
        "amount": 400
      },
      "gross_sales_money": {
        "currency_code": "USD",
        "amount": 450
      },
      "discount_money": {
        "currency_code": "USD",
        "amount": -45
      },
      "net_sales_money": {
        "currency_code": "USD",
        "amount": 405
      },
      "taxes": [
        {
          "name": "Sales tax",
          "rate": "0.060000",
          "inclusion_type": "ADDITIVE",
          "applied_money": {
            "currency_code": "USD",
            "amount": 24
          },
          "fee_id": "19498df7-3fb0-4c96-8b47-860480718abk"
        }
      ],
      "discounts": [
        {
          "name": "Early Bird",
          "applied_money": {
            "currency_code": "USD",
            "amount": -45
          },
          "discount_id": "0f075287-094c-4de7-9e23-cff5d41c910b"
        }
      ],
      "modifiers": [
        {
          "name": "Whipped Cream",
          "applied_money": {
            "currency_code": "USD",
            "amount": 50
          },
          "modifier_option_id": "39059fd0-ae9d-4eb3-b6e8-dd3198f019b8"
        }
      ]
    }
  ]
}

List Settlements

GET /v1/{location_id}/settlements

Provides summary information for all deposits and withdrawals initiated by Square to a merchant's bank account during a date range. Date ranges cannot exceed one year in length. See Date ranges for details of inclusive and exclusive dates.

Settlement objects returned by this endpoint do not include the entries field, which lists the transactions that contribute to the total of the settlement. To get a particular settlement's entries, use the Retrieve Settlement endpoint.

Square initiates its regular deposits to merchant bank accounts on the schedule indicated on this page. A deposit initiated by Square on a given day is usually not provided by this endpoint before 10 p.m. PST the same day.

Square does not know when an initiated settlement completes, only whether it has failed. A completed settlement is typically reflected in a merchant's bank account within three business days, but in exceptional cases it might take longer.

Required permissions: SETTLEMENTS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to list settlements for.

If you specify me, this endpoint returns settlements aggregated from all of the business' locations.

Get a business' locations with the List Locations endpoint.

Request Parameters

For GET and DELETE endpoints, you provide request parameters in a query string appended to the request URL.

NameTypeDescription
begin_time (optional)string

The beginning of the requested reporting period, in ISO 8601 format.

If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error.

Default value: The current time minus one year.

end_time (optional)string

The end of the requested reporting period, in ISO 8601 format.

If this value is more than one year greater than begin_time, this endpoint returns an error.

Default value: The current time.

order (optional)ListOrder

The order in which settlements are listed in the response.

Default value: ASC

limit (optional)number

The maximum number of settlements to return in a single response. This value cannot exceed 200.

This value is always an integer.

Default value: 100

status (optional)Settlement.Status

Provide this parameter to retrieve only settlements with a particular status (SENT or FAILED).

Return Value

An array of zero or more Settlement objects.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/settlements?begin_time=2013-01-15T00:00:00Z&end_time=2013-01-31T00:00:00Z

Example Response Body

[
  {
    "id": "C:34GEWHCJGPR40",
    "status": "SENT",
    "bank_account_id": "JGHJ0343",
    "initiated_at": "2013-01-02T08:00:00.000Z",
    "total_money": {
      "amount": 5981,
      "currency_code": "USD"
    }
  },
  ...
]

Retrieve Settlement

GET /v1/{location_id}/settlements/{settlement_id}

Provides comprehensive information for a single settlement, including the entries that contribute to the settlement's total.

See SettlementEntry.Type for descriptions of the types of entries that compose a settlement.

Required permissions: SETTLEMENTS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the settlement's associated location.

Get a business' locations with the List Locations endpoint.

settlement_idstring

The settlement's Square-issued ID. You obtain this value from Settlement objects returned by the List Settlements endpoint.

Return Value

A Settlement object that describes the requested settlement.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/settlements/C:34GEWHCJGPR40

Example Response Body

{
  "id": "C:34GEWHCJGPR40",
  "status": "SENT",
  "bank_account_id": "543654645",
  "initiated_at": "2013-01-02T08:00:00.000Z",
  "total_money": {
    "amount": 5981,
    "currency_code": "USD"
  },
  "entries": [
    {
      "payment_id": "Jq74mCczmFXk1tC10GB",
      "type": "CHARGE",
      "amount_money": {
        "amount": 5981,
        "currency_code": "USD"
      },
      "fee_money": {
        "amount": -169,
        "currency_code": "USD"
      }
    },
    ...
  ]
}

Create Refund

POST /v1/{location_id}/refunds

Issues a refund for a previously processed payment. You must issue a refund within 120 days of the associated payment. See this article for more information on refund behavior.

Issuing a refund for a card payment is not reversible. To develop against this endpoint, you can create fake cash payments in Square Point of Sale and refund them.

You can issue either full refunds or partial refunds. If you issue a partial refund, you must specify the amount of money to refund.

Required permissions: PAYMENTS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the original payment's associated location.

Get a business' locations with the List Locations endpoint.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
payment_idstring

The ID of the payment to refund.

If you're creating a PARTIAL refund for a split tender payment, instead provide the id of the particular tender you want to refund. See Split Tender Payments for details.

typeRefund.Type

The type of refund (FULL or PARTIAL).

reasonstring

The reason for the refund.

refunded_moneyMoney

The amount of money to refund. Required only for PARTIAL refunds.

The value of amount must be negative.

request_idempotence_key (optional)string

An optional key to ensure idempotence if you issue the same PARTIAL refund request more than once.

If you attempt to issue a partial refund and you aren't sure whether your request succeeded, you can safely repeat your request with the same request_idempotence_key. If you want to issue another partial refund for the same payment, you must use a request_idempotence_key that is unique among refunds you have issued for the payment.

Return Value

A Refund object representing the issued refund.

Example Request Body

{
  "payment_id": "Jq74mCczmFXk1tC10GB",
  "type": "PARTIAL",
  "reason": "Returned Goods",
  "refunded_money": {
    "amount": -500,
    "currency_code": "USD"
  },
  "request_idempotence_key": "1"
}

Example Response Body

{
  "type": "PARTIAL",
  "created_at": "2013-01-17T01:33:23Z",
  "processed_at": "2013-01-17T01:33:23Z",
  "reason": "Returned Goods",
  "refunded_money": {
    "currency_code": "USD",
    "amount": -500
  },
  "payment_id": "Jq74mCczmFXk1tC10GB"
}

List Refunds

GET /v1/{location_id}/refunds

Provides the details for all refunds initiated by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length. See Date ranges for details of inclusive and exclusive dates.

Required permissions: PAYMENTS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to list refunds for.

If you specify me, this endpoint returns refunds aggregated from all of the business' locations.

Get a business' locations with the List Locations endpoint.

Request Parameters

For GET and DELETE endpoints, you provide request parameters in a query string appended to the request URL.

NameTypeDescription
begin_time (optional)string

The beginning of the requested reporting period, in ISO 8601 format.

If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error.

Default value: The current time minus one year.

end_time (optional)string

The end of the requested reporting period, in ISO 8601 format.

If this value is more than one year greater than begin_time, this endpoint returns an error.

Default value: The current time.

order (optional)ListOrder

The order in which refunds are listed in the response.

Default value: ASC

limit (optional)number

The maximum number of refunds to return in a single response. This value cannot exceed 200.

This value is always an integer.

Default value: 100

Return Value

An array of zero or more Refund objects.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/refunds?begin_time=2013-01-15T00:00:00Z&end_time=2013-01-31T00:00:00Z

Example Response Body

[
  {
    "type": "FULL",
    "created_at": "2013-01-17T01:33:23Z",
    "processed_at": "2013-01-17T01:33:23Z",
    "reason": "Returned Goods",
    "refunded_money": {
      "currency_code": "USD",
      "amount": -5981
    },
    "payment_id": "Jq74mCczmFXk1tC10GB"
  },
  ...
]

List Orders

GET /v1/{location_id}/orders

Provides summary information for a merchant's online store orders.

Order objects returned by this endpoint do not include the order_history field, which lists prior activity related to the order. To get a particular order's history, use the Retrieve Order endpoint.

Note that Order objects do not include a list of the items purchased. To get the items purchased in an order, provide the order's payment_id to the Retrieve Payment endpoint. The itemizations field of the returned Payment object lists the items purchased.

Required permissions: ORDERS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to list online store orders for.

Get a business' locations with the List Locations endpoint.

Request Parameters

For GET and DELETE endpoints, you provide request parameters in a query string appended to the request URL.

NameTypeDescription
limit (optional)number

The maximum number of orders to return in a single response. This value cannot exceed 200.

This value is always an integer.

Default value: 100

order (optional)ListOrder

Indicates whether orders are listed in chronological (ASC) or reverse-chronological (DESC) order.

Default value: ASC

Return Value

An array of zero or more Order objects.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/orders?order=DESC

Retrieve Order

GET /v1/{location_id}/orders/{order_id}

Provides comprehensive information for a single online store order, including the order's history.

The Order objects returned by this endpoint do not include a list of the items purchased. To get the items purchased, provide the payment_id of the order to the Retrieve Payment endpoint. The itemizations field of the returned Payment object lists the items purchased.

Required permissions: ORDERS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the order's associated location.

Get a business' locations with the List Locations endpoint.

order_idstring

The order's Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint.

Return Value

An Order object that describes the requested order.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/orders/ORDER_ID

Update Order

PUT /v1/{location_id}/orders/{order_id}

Updates the details of an online store order. Every update you perform on an order corresponds to one of three actions:

  • Completing the order (the order has been shipped or otherwise fulfilled)
  • Canceling the order
  • Refunding a previously completed order

Note that to COMPLETE or CANCEL an order, its current state must be OPEN. To REFUND an order, its current state must be COMPLETED.

If you REFUND an order, a refund is initiated for the order's associated payment.

Required permissions: ORDERS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the order's associated location.

Get a business' locations with the List Locations endpoint.

order_idstring

The ID of the order to modify.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
actionOrder.Action

The action to perform on the order (COMPLETE, CANCEL, or REFUND).

shipped_tracking_number (optional)string

The tracking number of the shipment associated with the order. Only valid if action is COMPLETE.

completed_note (optional)string

A merchant-specified note about the completion of the order. Only valid if action is COMPLETE.

refunded_note (optional)string

A merchant-specified note about the refunding of the order. Only valid if action is REFUND.

canceled_note (optional)string

A merchant-specified note about the canceling of the order. Only valid if action is CANCEL.

Return Value

An Order object that represents the updated order.

List Bank Accounts

GET /v1/{location_id}/bank-accounts

Provides non-confidential details for all of a location's associated bank accounts. This endpoint does not provide full bank account numbers, and there is no way to obtain a full bank account number with the Connect API.

Required permissions: BANK_ACCOUNTS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to list bank accounts for.

Get a business' locations with the List Locations endpoint.

Return Value

An array of BankAccount objects describing the merchant's bank accounts.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/bank-accounts

Example Response Body

[
  {
    "id": "JGHJ0343",
    "merchant_id": "AV76FTXT15L",
    "bank_name": "Chase",
    "name": "Dave's Business Account",
    "type": "CHECKING",
    "routing_number": "012345678",
    "account_number_suffix": "1234",
    "currency_code": "USD"
  }
]

Retrieve Bank Account

GET /v1/{location_id}/bank-accounts/{bank_account_id}

Provides non-confidential details for a merchant's associated bank account. This endpoint does not provide full bank account numbers, and there is no way to obtain a full bank account number with the Connect API.

Required permissions: BANK_ACCOUNTS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the bank account's associated location.

Get a business' locations with the List Locations endpoint.

bank_account_idstring

The bank account's Square-issued ID. You obtain this value from Settlement objects returned by the List Settlements endpoint.

Return Value

A BankAccount object describing your bank account.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/bank-accounts/YOUR_BANK_ACCOUNT_ID

Example Response Body

{
  "id": "JGHJ0343",
  "merchant_id": "AV76FTXT15L",
  "bank_name": "Chase",
  "name": "Dave's Business Account",
  "type": "CHECKING",
  "routing_number": "012345678",
  "account_number_suffix": "1234",
  "currency_code": "USD"
}

Item Management

Item Management Overview

Square merchants can create, modify, and delete items and related entities with these endpoints. Changes made with these endpoints automatically sync with the merchant dashboard and all of a merchant's instances of Square Point of Sale.

Most of these tasks can also be performed from the merchant dashboard.

Note: Deleted entities cannot be retrieved or undeleted.

Entity descriptions

Item-related entities include the following:

Items

Items represent the base products a business offers for sale. An item can represent a physical product, a service, or anything in between.

Item objects themselves do not have a price or SKU. Rather, every item has one or more variations that each have a price and SKU.

Items are listed on the Item Library page of the merchant dashboard.

Examples: Popcorn, Backpack

Variations

Item variations are distinct versions of an item for sale, each with their own price, SKU, and inventory. Every variation belongs to exactly one item.

Variations are listed on an item's detail page, available from the Item Library page of the merchant dashboard.

Examples:Large popcorn, Green backpack

Modifiers

Item modifiers are options you can apply to an item variation to customize it. A modifier can be applied to any variation of a given item, or even to variations of completely different items.

In practice, merchants have a number of modifier lists, each of which contains one or more modifier options. Each modifier list indicates whether more than one of its options can be applied to a single purchased item. Each modifier option has its own price.

After you create a modifier list, you can use the Apply Modifier List endpoint to associate it with a given item, and you can use the Remove Modifier List endpoint to remove this association.

Modifiers are listed on the Modifiers page of the merchant dashboard.

Examples: Toppings (for popcorn), Monogram options (for backpack)

Categories

Item categories provide a basic structure for organizing your items. Each item can belong to at most one category.

Categories are listed on the Categories page of the merchant dashboard.

Examples: Snacks (for popcorn), Luggage (for backpack)

Discounts

Discounts are a percentage or a flat amount. They can either have a fixed value or have their value entered at the time of sale.

Discounts are applied to the pre-tax total of an entire purchase, not to an individual item in the purchase.

Discounts are listed on the Discounts page of the merchant dashboard.

Examples: Matinee 10% discount, Loyal customer $5 discount

Fees (taxes)

Fees are percentage-based and are applied to individual items in a sale. Currently, all fees are taxes. Note that these are merchant-specified fees that a buyer pays, not Square transaction fees that a merchant pays.

Each item specifies which fees are applied to it by default, although a merchant can override these defaults at the time of sale. When you create a fee with the Create Fee endpoint, it isn't automatically applied to any items. You can use the Apply Fee endpoint to associate a fee with a given item, and you can use the Remove Fee endpoint to remove this association.

A fee can have one of two inclusion types: additive or inclusive.

  • Additive fees are added on top of the price of items they're applied to. If an additive 10% fee is applied to a $100 item, the total is $110.
  • Inclusive fees are assumed to already be included in the price of the items they apply to. If an inclusive 10% fee is applied to a $100 item, the total is $100, and the actual base cost of the item is assumed to be $90.91. This affects the amount of any additive fees that are also applied to the item.

Fees can be applied during one of two phases of a payment: the subtotal phase or the total phase.

  • Fees applied during the subtotal phase are applied only to the base cost of applicable items. The vast majority of taxes are applied during this phase.
  • Fees applied during the total phase are applied to the base cost of applicable items, and to any fee amounts applied to those items during the subtotal phase.

Fees are listed on the Taxes page of the merchant dashboard.

Examples: Sales tax

Favorites Pages

The iPad and Android tablet versions of Square Point of Sale support Favorites pages, which provide merchants quick access to entities of their choosing. Each page is a five-by-five grid, where each non-empty cell in the grid represents one of the following:

  • An item
  • A category
  • A discount
  • A placeholder

Placeholders are the following special cells that merchants can add to their favorites pages:

  • The "All Items" cell, which lists all of a merchant's items
  • The "Discounts" cell, which lists all of a merchant's discounts
  • The "Redeem Rewards" cell (available to eligible merchants)

Favorites pages are currently viewable only from the iPad and Android tablet versions of Square Point of Sale.

Managing inventory

If you've enabled inventory tracking for some or all of your item variations, you can get the current inventory of those variations with the List Inventory endpoint. You can also use the Adjust Inventory endpoint to change a variation's available quantity.

Note that you don't need to decrement a merchant's available quantity when they sell a variation with Square Point of Sale or from their online store (this happens automatically).

Enabling inventory tracking

To enable inventory tracking for an existing item variation, use the Update Variation endpoint to set the variation's track_inventory field to true. You can do this for new variations by providing this value to the Create Variation endpoint.

You can also use these endpoints to configure whether an alert is generated when a variation's available quantity is low. These alerts are displayed in the merchant dashboard, and daily notification emails are sent to a merchant if at least one variation's quantity falls below a specified threshold.

Associating entities with an external system

Item-related entities include fields you can use to associate them with entities in a non-Square system.

  • When you create an item-related entity, you can optionally specify its id. This value must be unique among all IDs ever specified on the merchant's behalf, including those specified by other applications. You can never reuse an entity ID. If you don't specify an id, Square generates one for the entity.
  • Item variations have a user_data string that lets you associate arbitrary metadata with the variation. The string cannot exceed 255 characters. You can set the value of this string with any endpoint that creates or updates a variation.

Create Item

POST /v1/{location_id}/items

Creates an item and at least one variation for it.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to create an item for.

Get a business' locations with the List Locations endpoint.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
id (optional)string

The item's ID. Must be unique among all entity IDs ever provided on behalf of the merchant. You can never reuse an ID. This value can include alphanumeric characters, dashes (-), and underscores (_).

If you don't provide this value, an ID is generated by Square.

namestring

The item's name.

description (optional)string

The item's description.

category_id (optional)string

The ID of the item's category, if any.

color (optional)Item.Color

The color of the item's display label in Square Point of Sale.

Default value: 9da2a6

abbreviation (optional)string

The text of the item's display label in Square Point of Sale. Only up to the first five characters of the string are used.

Default value: The first two characters of the item's name.

visibility (optional)Item.Visibility

Indicates whether the item is viewable from the merchant's online store (PUBLIC) or PRIVATE.

Default value: PUBLIC

available_online (optional)boolean

If true, the item can be added to shipping orders from the merchant's online store.

Default value: false

available_for_pickup (optional)boolean

If true, the item can be added to pickup orders from the merchant's online store.

Default value: false

variationsItemVariation[]

The item's variations. You must specify at least one variation.

Return Value

An Item object that represents the created item.

Example Request Body

{
  "name": "Milkshake",
  "description": "It's better than yours",
  "visibility": "PRIVATE",
  "variations": [
    {
      "name": "Small",
      "pricing_type": "FIXED_PRICING",
      "price_money": {
        "currency_code": "USD",
        "amount": 400
      },
      "sku": "123"
    }
  ]
}

Example Response Body

{
  "id": "442d1344-6d2b-4238-83d0-0284dfd335d8",
  "name": "Milkshake",
  "description": "It's better than yours",
  "type": "NORMAL",
  "visibility": "PRIVATE",
  "available_online": false,
  "variations": [
    {
      "id": "cb890728-cfdc-4690-9e03-349f964f756r",
      "name": "Small",
      "pricing_type": "FIXED_PRICING",
      "price_money": {
        "currency_code": "USD",
        "amount": 400
      },
      "ordinal": 0,
      "item_id": "442d1344-6d2b-4238-83d0-0284dfd335d8"
    }
  ]
}

List Items

GET /v1/{location_id}/items

Provides summary information for all of a location's items.

Required permissions: ITEMS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to list items for.

Get a business' locations with the List Locations endpoint.

Return Value

An array of zero or more Item objects. These objects do not include modifier_lists or fees fields. To get an item's associated modifier lists and fees, use the Retrieve Item endpoint.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/items

Example Response Body

[
  {
    "id": "442d1344-6d2b-4238-83d0-0284dfd335d8",
    "name": "Milkshake",
    "description": "It's better than yours",
    "visibility": "PRIVATE",
    "type": "NORMAL",
    "available_online": false,
    "category": {
      "id": "36ac7016-3a4e-4934-81f1-9057ac613f2y",
      "name": "Beverages"
    },
    "variations": [
      {
        "id": "cb890728-cfdc-4690-9e03-349f964f756r",
        "name": "Small",
        "pricing_type": "FIXED_PRICING",
        "price_money": {
          "currency_code": "USD",
          "amount": 400
        },
        "ordinal": 0,
        "item_id": "442d1344-6d2b-4238-83d0-0284dfd335d8"
      },
      ...
    ]
  },
  ...
]

Retrieve Item

GET /v1/{location_id}/items/{item_id}

Provides the details for a single item, including associated modifier lists and fees.

Required permissions: ITEMS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the item's associated location.

Get a business' locations with the List Locations endpoint.

item_idstring

The item's ID.

Return Value

An Item object that describes the requested item.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/items/ITEM_ID

Example Response Body

{
  "id": "442d1344-6d2b-4238-83d0-0284dfd335d8",
  "name": "Milkshake",
  "description": "It's better than yours",
  "type": "NORMAL",
  "visibility": "PRIVATE",
  "available_online": false,
  "category": {
    "id": "36ac7016-3a4e-4934-81f1-9057ac613f2y",
    "name": "Beverages"
  },
  "variations": [
    {
      "id": "cb890728-cfdc-4690-9e03-349f964f756r",
      "name": "Small",
      "pricing_type": "FIXED_PRICING",
      "price_money": {
        "currency_code": "USD",
        "amount": 400
      },
      "ordinal": 0,
      "item_id": "442d1344-6d2b-4238-83d0-0284dfd335d8"
    },
    ...
  ],
  "modifier_lists": [
    {
      "id": "dcd7e350-c50f-421f-ada1-23a825b008b2",
      "name": "Toppings",
      "selection_type": "MULTIPLE",
      "modifier_options": [
        {
          "id": "39059fd0-ae9d-4eb3-b6e8-dd3198f019b8",
          "name": "Whipped Cream",
          "price_money": {
            "currency_code": "USD",
            "amount": 50
          },
          "on_by_default": false,
          "ordinal": 1,
          "modifier_list_id": "dcd7e350-c50f-421f-ada1-23a825b008b2"
        },
        ...
      ]
    }
    ...
  ],
  "fees": [
    {
      "id": "19498df7-3fb0-4c96-8b47-860480718abk",
      "name": "Sales tax",
      "adjustment_type": "TAX",
      "rate": "0.06",
      "calculation_phase": "FEE_SUBTOTAL_PHASE",
      "applies_to_custom_amounts": true,
      "enabled": true,
      "inclusion_type": "INCLUSIVE"
    },
    ...
  ]
}

Update Item

PUT /v1/{location_id}/items/{item_id}

Modifies the core details of an existing item.

If you want to modify an item's variations, use the Update Variation endpoint instead.

If you want to add or remove a modifier list from an item, use the Apply Modifier List and Remove Modifier List endpoints instead.

If you want to add or remove a fee from an item, use the Apply Fee and Remove Fee endpoints instead.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the item's associated location.

Get a business' locations with the List Locations endpoint.

item_idstring

The ID of the item to modify.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
name (optional)string

The item's name.

description (optional)string

The item's description.

category_id (optional)string

The ID of the item's category, if any.

If you provide the empty string for this value, any existing category association is removed from the item.

color (optional)Item.Color

The color of the item's display label in Square Point of Sale.

abbreviation (optional)string

The text of the item's display label in Square Point of Sale. Only up to the first five characters of the string are used.

visibility (optional)Item.Visibility

Indicates whether the item is viewable from the merchant's online store (PUBLIC) or PRIVATE.

available_online (optional)boolean

If true, the item can be purchased from the merchant's online store.

available_for_pickup (optional)boolean

If true, the item can be added to pickup orders from the merchant's online store.

Return Value

An Item object that represents the updated item.

Example Request Body

{
  "name": "Milkshake",
  "description": "It's better than yours",
  "visibility": "PRIVATE"
}

Example Response Body

{
  "id": "442d1344-6d2b-4238-83d0-0284dfd335d8",
  "name": "Milkshake",
  "description": "It's better than yours",
  "type": "NORMAL",
  "visibility": "PRIVATE",
  "available_online": false,
  "category": {
    "id": "36ac7016-3a4e-4934-81f1-9057ac613f2y",
    "name": "Beverages"
  },
  "variations": [
    {
      "id": "cb890728-cfdc-4690-9e03-349f964f756r",
      "name": "Small",
      "pricing_type": "FIXED_PRICING",
      "price_money": {
        "currency_code": "USD",
        "amount": 400
      },
      "ordinal": 0,
      "item_id": "442d1344-6d2b-4238-83d0-0284dfd335d8"
    }
  ]
}

Delete Item

DELETE /v1/{location_id}/items/{item_id}

Deletes an existing item and all item variations associated with it.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the item's associated location.

Get a business' locations with the List Locations endpoint.

item_idstring

The ID of the item to delete.

Return Value

If the request succeeds, the endpoint returns a 200 status code and an empty JSON object, {}.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/items/ITEM_ID

Upload Item Image

POST /v1/{location_id}/items/{item_id}/image

Uploads a JPEG or PNG image and sets it as the master image for an item. See this article for recommended specifications for item images.

If you upload an image for an item that already has a master image, the new image replaces the existing one.

Important: Requests to this endpoint use the Content-Type: multipart/form-data header instead of Content-Type: application/json. It's recommended that you use an HTTP library (such as Requests for Python) that simplifies the process for sending multipart/form-data requests.

The example request body shown assumes that you've set your request's multipart boundary to BOUNDARY in your Content-Type header, like so:

Content-Type: multipart/form-data; boundary=BOUNDARY

Note that some HTTP libraries set your request's multipart boundary for you.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the item's associated location.

Get a business' locations with the List Locations endpoint.

item_idstring

The ID of the item to associate the image with.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
image_datadata

The image's binary data.

Return Value

An ItemImage object that represents the uploaded image.

Example Request Body

--BOUNDARY
Content-Disposition: form-data; name="image_data"; filename="MyImage.png"
Content-Type: image/png
IMAGE BINARY DATA GOES HERE
--BOUNDARY--

Example Response Body

{
  "id": "db84c493-6129-43c9-856f-f3f2818dc244",
  "url": "https://d2isyty7gbnm74.cloudfront.net/38bPVNsCIkw-6fAzaFeck8Kx_XQ=/https://square-production.s3.amazonaws.com/files/61ebb5e4ab59428dd765893ce211a9ae/original.jpeg"
}

Create Variation

POST /v1/{location_id}/items/{item_id}/variations

Creates an item variation for an existing item.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
merchant_idstring

The ID of the item's associated location.

Get a business' locations with the List Locations endpoint.

item_idstring

The ID of the item the variation applies to.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
id (optional)string

The variation's ID. Must be unique among all entity IDs ever provided on behalf of the merchant. You can never reuse an ID. This value can include alphanumeric characters, dashes (-), and underscores (_).

If you don't provide this value, an ID is generated by Square.

namestring

The item variation's name.

pricing_type (optional)ItemVariation.PricingType

Indicates whether the item variation's price is fixed or determined at the time of sale.

Default value: FIXED_PRICING

price_moneyMoney

The item variation's price, if any.

sku (optional)string

The item variation's SKU, if any.

track_inventory (optional)boolean

If true, inventory tracking is active for the variation.

Default value: false

inventory_alert_type (optional)InventoryAlertType

Indicates whether the item variation displays an alert when its inventory quantity is less than or equal to its inventory_alert_threshold.

Default value: NONE

inventory_alert_threshold (optional)number

If the inventory quantity for the variation is less than or equal to this value and inventory_alert_type is LOW_QUANTITY, the variation displays an alert in the merchant dashboard.

This value is always an integer.

Default value: 0

user_datastring

Arbitrary metadata to associate with the variation. Cannot exceed 255 characters.

Return Value

An ItemVariation object that represents the created variation.

Example Request Body

{
  "name": "Small",
  "price_money": {
    "currency_code": "USD",
    "amount": 400
  },
  "track_inventory": true,
  "inventory_alert_type": "LOW_QUANTITY",
  "inventory_alert_threshold": 10,
  "user_data": "SEASONAL=TRUE"
}

Example Response Body

{
  "pricing_type": "FIXED_PRICING",
  "track_inventory": true,
  "inventory_alert_type": "LOW_QUANTITY",
  "id": "cb890728-cfdc-4690-9e03-349f964f756r",
  "name": "Small",
  "price_money": {
    "currency_code": "USD",
    "amount": 400
  },
  "ordinal": 0,
  "item_id": "442d1344-6d2b-4238-83d0-0284dfd335d8",
  "inventory_alert_threshold": 10,
  "user_data": "SEASONAL=TRUE"
}

Update Variation

PUT /v1/{location_id}/items/{item_id}/variations/{variation_id}

Modifies the details of an existing item variation.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the variation's associated location.

Get a business' locations with the List Locations endpoint.

item_idstring

The ID of the item the variation applies to.

variation_idstring

The ID of the variation to modify.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
name (optional)string

The item variation's name.

pricing_type (optional)ItemVariation.PricingType

Indicates whether the item variation's price is fixed or determined at the time of sale.

Default value: FIXED_PRICING

price_money (optional)Money

The item variation's price, if any.

sku (optional)string

The item variation's SKU, if any.

track_inventory (optional)boolean

If true, inventory tracking is active for the variation.

inventory_alert_type (optional)InventoryAlertType

Indicates whether the item variation displays an alert when its inventory quantity goes below its inventory_alert_threshold.

inventory_alert_threshold (optional)number

If the inventory quantity for the variation is below this value and inventory_alert_type is LOW_QUANTITY, the variation displays an alert in the merchant dashboard.

user_datastring

Arbitrary metadata to associate with the variation. Cannot exceed 255 characters.

Return Value

An ItemVariation object that represents the updated variation.

Example Request Body

{
  "name": "Small",
  "price_money": {
    "currency_code": "USD",
    "amount": 400
  },
  "track_inventory": true,
  "inventory_alert_type": "LOW_QUANTITY",
  "inventory_alert_threshold": 10,
  "user_data": "SEASONAL=TRUE"
}

Example Response Body

{
  "pricing_type": "FIXED_PRICING",
  "track_inventory": true,
  "inventory_alert_type": "LOW_QUANTITY",
  "id": "cb890728-cfdc-4690-9e03-349f964f756r",
  "name": "Small",
  "price_money": {
    "currency_code": "USD",
    "amount": 400
  },
  "ordinal": 0,
  "item_id": "442d1344-6d2b-4238-83d0-0284dfd335d8",
  "inventory_alert_threshold": 10,
  "user_data": "SEASONAL=TRUE"
}

Delete Variation

DELETE /v1/{location_id}/items/{item_id}/variations/{variation_id}

Deletes an existing item variation from an item.

Every item must have at least one varation. This endpoint returns an error if you attempt to delete an item's only variation.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the variation's associated location.

Get a business' locations with the List Locations endpoint.

item_idstring

The ID of the item the variation applies to.

variation_idstring

The ID of the variation to delete.

Return Value

If the request succeeds, the endpoint returns a 200 status code and an empty JSON object, {}.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/items/ITEM_ID/variations/VARIATION_ID

List Inventory

GET /v1/{location_id}/inventory

Provides inventory information for all of a merchant's inventory-enabled item variations.

See Managing inventory to learn how to enable an item variation for inventory tracking.

Required permissions: ITEMS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to list inventory for.

Get a business' locations with the List Locations endpoint.

Request Parameters

For GET and DELETE endpoints, you provide request parameters in a query string appended to the request URL.

NameTypeDescription
limitnumber

The maximum number of inventory entries to return in a single response. This value cannot exceed 1000.

This value is always an integer.

Default value: 1000

Return Value

An array of zero or more InventoryEntry objects.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/inventory?limit=250

Example Response Body

[
  {
    "variation_id": "cb890728-cfdc-4690-9e03-349f964f756r",
    "quantity_on_hand": 50
  },
  ...
]

Adjust Inventory

POST /v1/{location_id}/inventory/{variation_id}

Adjusts an item variation's current available inventory.

See Managing inventory to learn how to enable an item variation for inventory tracking.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the variation's associated location.

Get a business' locations with the List Locations endpoint.

variation_idstring

The ID of the variation to adjust inventory information for.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
quantity_deltanumber

The number to adjust the variation's quantity by.

This value must be negative if adjustment_type is SALE, and it must be positive if adjustment_type is RECEIVE_STOCK.

adjustment_typeInventoryAdjustmentType

The reason for the inventory adjustment.

memo (optional)string

A note about the inventory adjustment.

Return Value

An InventoryEntry object that represents the variation's new inventory information.

Example Request Body

{
  "quantity_delta": -1,
  "adjustment_type": "SALE"
}

Example Response Body

{
  "variation_id": "cb890728-cfdc-4690-9e03-349f964f756r",
  "quantity_on_hand": 49
}

Create Modifier List

POST /v1/{location_id}/modifier-lists

Creates an item modifier list and at least one modifier option for it.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to create a modifier list for.

Get a business' locations with the List Locations endpoint.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
id (optional)string

The modifier list's ID. Must be unique among all entity IDs ever provided on behalf of the merchant. You can never reuse an ID. This value can include alphanumeric characters, dashes (-), and underscores (_).

If you don't provide this value, an ID is generated by Square.

namestring

The modifier list's name.

selection_type (optional)ModifierList.SelectionType

Indicates whether multiple options from the modifier list can be applied to a single item.

Default value: SINGLE

modifier_optionsModifierOption[]

The options included in the modifier list. You must include at least one modifier option.

Return Value

A ModifierList object that represents the created modifier list.

Example Request Body

{
  "name": "Toppings",
  "selection_type": "MULTIPLE",
  "modifier_options": [
    {
      "name": "Whipped Cream",
      "price_money": {
        "currency_code": "USD",
        "amount": 50
      }
    }
  ]
}

Example Response Body

{
  "selection_type": "MULTIPLE",
  "id": "dcd7e350-c50f-421f-ada1-23a825b008b2",
  "name": "Toppings",
  "modifier_options": [
    {
      "id": "39059fd0-ae9d-4eb3-b6e8-dd3198f019b8",
      "price_money": {
        "currency_code": "USD",
        "amount": 50
      },
      "on_by_default": false,
      "name": "Whipped Cream",
      "ordinal": 0,
      "modifier_list_id": "dcd7e350-c50f-421f-ada1-23a825b008b2"
    }
  ]
}

List Modifier Lists

GET /v1/{location_id}/modifier-lists

Lists all of a location's modifier lists.

Required permissions: ITEMS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to list modifier lists for.

Get a business' locations with the List Locations endpoint.

Return Value

An array of zero or more ModifierList objects.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/modifier-lists

Example Response Body

[
  {
    "id": "dcd7e350-c50f-421f-ada1-23a825b008b2",
    "name": "Toppings",
    "selection_type": "MULTIPLE",
    "modifier_options": [
      {
        "id": "39059fd0-ae9d-4eb3-b6e8-dd3198f019b8",
        "name": "Whipped Cream",
        "price_money": {
          "currency_code": "USD",
          "amount": 50
        },
        "on_by_default": false,
        "ordinal": 1,
        "modifier_list_id": "dcd7e350-c50f-421f-ada1-23a825b008b2"
      },
      ...
    ]
  }
  ...
]

Retrieve Modifier List

GET /v1/{location_id}/modifier-lists/{modifier_list_id}

Provides the details for a single modifier list.

Required permissions: ITEMS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the modifier list's associated location.

Get a business' locations with the List Locations endpoint.

modifier_list_idstring

The modifier list's ID.

Return Value

A ModifierList object that describes the requested modifier list.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/modifier-lists/MODIFIER_LIST_ID

Example Response Body

{
  "id": "dcd7e350-c50f-421f-ada1-23a825b008b2",
  "name": "Toppings",
  "selection_type": "MULTIPLE",
  "modifier_options": [
    {
      "id": "39059fd0-ae9d-4eb3-b6e8-dd3198f019b8",
      "name": "Whipped Cream",
      "price_money": {
        "currency_code": "USD",
        "amount": 50
      },
      "on_by_default": false,
      "ordinal": 1,
      "modifier_list_id": "dcd7e350-c50f-421f-ada1-23a825b008b2"
    },
    ...
  ]
}

Update Modifier List

PUT /v1/{location_id}/modifier-lists/{modifier_list_id}

Modifies the details of an existing item modifier list.

If you want to modify the details of a single modifier option, use the Update Modifier Option endpoint instead.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the modifier list's associated location.

Get a business' locations with the List Locations endpoint.

modifier_list_idstring

The ID of the modifier list to edit.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
name (optional)string

The modifier list's name.

selection_type (optional)ModifierList.SelectionType

Indicates whether multiple options from the modifier list can be applied to a single item.

Return Value

A ModifierList object that represents the updated modifier list.

Example Request Body

{
  "name": "Toppings",
  "selection_type": "MULTIPLE"
}

Example Response Body

{
  "selection_type": "MULTIPLE",
  "id": "dcd7e350-c50f-421f-ada1-23a825b008b2",
  "name": "Toppings",
  "modifier_options": [
    {
      "id": "39059fd0-ae9d-4eb3-b6e8-dd3198f019b8",
      "price_money": {
        "currency_code": "USD",
        "amount": 50
      },
      "on_by_default": false,
      "name": "Whipped Cream",
      "ordinal": 0,
      "modifier_list_id": "dcd7e350-c50f-421f-ada1-23a825b008b2"
    }
  ]
}

Delete Modifier List

DELETE /v1/{location_id}/modifier-lists/{modifier_list_id}

Deletes an existing item modifier list and all modifier options associated with it.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the modifier list's associated location.

Get a business' locations with the List Locations endpoint.

modifier_list_idstring

The ID of the modifier list to delete.

Return Value

If the request succeeds, the endpoint returns a 200 status code and an empty JSON object, {}.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/modifier-lists/MODIFIER_LIST_ID

Apply Modifier List

PUT /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id}

Associates a modifier list with an item, meaning modifier options from the list can be applied to the item.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the modifier list's associated location.

Get a business' locations with the List Locations endpoint.

item_idstring

The ID of the item to add the modifier list to.

modifier_list_idstring

The ID of the modifier list to apply.

Return Value

An Item object that represents the item with the specified modifier list added.

Example Request Body

https://connect.squareup.com/v1/LOCATION_ID/items/ITEM_ID/modifier-lists/MODIFIER_LIST_ID

Remove Modifier List

DELETE /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id}

Removes a modifier list association from an item, meaning modifier options from the list can no longer be applied to the item.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the modifier list's associated location.

Get a business' locations with the List Locations endpoint.

item_idstring

The ID of the item to remove the modifier list from.

modifier_list_idstring

The ID of the modifier list to remove.

Return Value

An Item object that represents the item with the specified modifier list removed.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/items/ITEM_ID/modifier-lists/MODIFIER_LIST_ID

Create Modifier Option

POST /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options

Creates an item modifier option and adds it to a modifier list.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the modifier list's associated location.

Get a business' locations with the List Locations endpoint.

modifier_list_idstring

The ID of the modifier list to add the option to.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
id (optional)string

The modifier option's ID. Must be unique among all entity IDs ever provided on behalf of the merchant. You can never reuse an ID. This value can include alphanumeric characters, dashes (-), and underscores (_).

If you don't provide this value, an ID is generated by Square.

namestring

The modifier option's name.

price_moneyMoney

The modifier option's price.

on_by_default (optional)boolean

If true, the modifier option is the default option in a modifier list for which selection_type is SINGLE.

Default value: false

Return Value

A ModifierOption object that represents the created modifier option.

Example Request Body

{
  "name": "Sprinkles",
  "price_money": {
    "currency_code": "USD",
    "amount": 50
  }
}

Example Response Body

{
  "id": "2009dd06-4fee-492b-bcff-ff7b45404557"
  "price_money": {
    "currency_code": "USD",
    "amount": 50
  }
  "on_by_default": false
  "name": "Sprinkles"
  "ordinal": 1
  "modifier_list_id": "dcd7e350-c50f-421f-ada1-23a825b008b2"
}

Update Modifier Option

PUT /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id}

Modifies the details of an existing item modifier option.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the modifier option's associated location.

Get a business' locations with the List Locations endpoint.

modifier_list_idstring

The ID of the modifier list that contains the option to edit.

modifier_option_idstring

The ID of the modifier option to edit.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
name (optional)string

The modifier option's name.

price_money (optional)Money

The modifier option's price.

on_by_default (optional)boolean

If true, the modifier option is the default option in a modifier list for which selection_type is SINGLE.

Return Value

A ModifierOption object that represents the updated modifier option.

Example Request Body

{
  "name": "Sprinkles",
  "price_money": {
    "currency_code": "USD",
    "amount": 50
  }
}

Example Response Body

{
  "id": "2009dd06-4fee-492b-bcff-ff7b45404557",
  "price_money": {
    "currency_code": "USD",
    "amount": 50
  },
  "on_by_default": false,
  "name": "Sprinkles",
  "ordinal": 1,
  "modifier_list_id": "dcd7e350-c50f-421f-ada1-23a825b008b2"
}

Delete Modifier Option

DELETE /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id}

Deletes an existing item modifier option from a modifier list.

Every modifier list must have at least one option. This endpoint returns an error if you attempt to delete a modifier list's only option.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the modifier option's associated location.

Get a business' locations with the List Locations endpoint.

modifier_list_idstring

The ID of the modifier list that contains the option.

modifier_option_idstring

The ID of the modifier option to delete.

Return Value

If the request succeeds, the endpoint returns a 200 status code and an empty JSON object, {}.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/modifier-lists/MODIFIER_LIST_ID/modifier-options/MODIFIER_OPTION_ID

Create Category

POST /v1/{location_id}/categories

Creates an item category.

To add or remove an item from a category, use the Update Item endpoint.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to create a category for.

Get a business' locations with the List Locations endpoint.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
id (optional)string

The category's ID. Must be unique among all entity IDs ever provided on behalf of the merchant. You can never reuse an ID. This value can include alphanumeric characters, dashes (-), and underscores (_).

If you don't provide this value, an ID is generated by Square.

namestring

The category's name.

Return Value

A Category object that represents the created category.

Example Request Body

{
  "name": "Beverages"
}

Example Response Body

{
  "id": "36ac7016-3a4e-4934-81f1-9057ac613f2y",
  "name": "Beverages"
}

List Categories

GET /v1/{location_id}/categories

Lists all of a location's item categories.

Required permissions: ITEMS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to list categories for.

Get a business' locations with the List Locations endpoint.

Return Value

An array of zero or more Category objects.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/categories

Example Response Body

[
  {
    "id": "36ac7016-3a4e-4934-81f1-9057ac613f2y",
    "name": "Beverages"
  },
  ...
]

Update Category

PUT /v1/{location_id}/categories/{category_id}

Modifies the details of an existing item category.

To add or remove an item from a category, use the Update Item endpoint.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the category's associated location.

Get a business' locations with the List Locations endpoint.

category_idstring

The ID of the category to edit.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
namestring

The new name of the category.

Return Value

A Category object that represents the updated category.

Example Request Body

{
  "name": "Beverages"
}

Example Response Body

{
  "id": "36ac7016-3a4e-4934-81f1-9057ac613f2y",
  "name": "Beverages"
}

Delete Category

DELETE /v1/{location_id}/categories/{category_id}

Deletes an existing item category.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the category's associated location.

category_idstring

The ID of the category to delete.

Return Value

If the request succeeds, the endpoint returns a 200 status code and an empty JSON object, {}.

Example Request

https://connect.squareup.com/v1/me/categories/CATEGORY_ID

Create Discount

POST /v1/{location_id}/discounts

Creates a discount.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to create a discount for.

Get a business' locations with the List Locations endpoint.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
id (optional)string

The discount's ID. Must be unique among all entity IDs ever provided on behalf of the merchant. You can never reuse an ID. This value can include alphanumeric characters, dashes (-), and underscores (_).

If you don't provide this value, an ID is generated by Square.

namestring

The discount's name.

rate (optional)string

The rate of the discount, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%. Specify a rate of 0 if discount_type is VARIABLE_PERCENTAGE.

Do not include this field for amount-based discounts.

amount_money (optional)Money

The amount of the discount. Specify an amount of 0 if discount_type is VARIABLE_AMOUNT.

Do not include this field for rate-based discounts.

discount_type (optional)Discount.Type

Indicates whether the discount is a FIXED value or entered at the time of sale.

Default value: FIXED

pin_required (optional)boolean

Indicates whether a mobile staff member needs to enter their PIN to apply the discount to a payment.

Default value: false

color (optional)Item.Color

The color of the discount's display label in Square Point of Sale.

Default value: 9da2a6

Return Value

A Discount object that represents the created discount.

Example Request Body

{
  "pin_required": false,
  "discount_type": "FIXED",
  "name": "Early Bird",
  "rate": "0.1"
}

Example Response Body

{
  "pin_required": false,
  "discount_type": "FIXED",
  "id": "0f075287-094c-4de7-9e23-cff5d41c910b",
  "name": "Early Bird",
  "rate": "0.1"
}

List Discounts

GET /v1/{location_id}/discounts

Lists all of a location's discounts.

Required permissions: ITEMS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to list discounts for.

Get a business' locations with the List Locations endpoint.

Return Value

An array of zero or more Discount objects.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/discounts

Example Response Body

[
  {
    "pin_required": false,
    "discount_type": "FIXED",
    "id": "0f075287-094c-4de7-9e23-cff5d41c910b",
    "name": "Early Bird",
    "rate": "0.1"
  },
  ...
]

Update Discount

PUT /v1/{location_id}/discounts/{discount_id}

Modifies the details of an existing discount.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the discount's associated location.

Get a business' locations with the List Locations endpoint.

discount_idstring

The ID of the discount to edit.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
name (optional)string

The discount's name.

rate (optional)string

The rate of the discount, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%. Specify a rate of 0 if discount_type is VARIABLE_PERCENTAGE.

Do not include this field for amount-based discounts.

amount_money (optional)Money

The amount of the discount. Specify an amount of 0 if discount_type is VARIABLE_AMOUNT.

Do not include this field for rate-based discounts.

discount_type (optional)Discount.Type

Indicates whether the discount is a FIXED value or entered at the time of sale.

Default value: FIXED

pin_required (optional)boolean

Indicates whether a mobile staff member needs to enter their PIN to apply the discount to a payment.

Default value: false

color (optional)Item.Color

The color of the discount's display label in Square Point of Sale.

Default value: 9da2a6

Return Value

A Discount object that represents the updated discount.

Example Request Body

{
  "pin_required": false,
  "discount_type": "FIXED",
  "name": "Early Bird",
  "rate": "0.1"
}

Example Response Body

{
  "pin_required": false,
  "discount_type": "FIXED",
  "id": "0f075287-094c-4de7-9e23-cff5d41c910b",
  "name": "Early Bird",
  "rate": "0.1"
}

Delete Discount

DELETE /v1/{location_id}/discounts/{discount_id}

Deletes an existing discount.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the discount's associated location.

Get a business' locations with the List Locations endpoint.

discount_idstring

The ID of the discount to delete.

Return Value

If the request succeeds, the endpoint returns a 200 status code and an empty JSON object, {}.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/discounts/DISCOUNT_ID

Create Fee

POST /v1/{location_id}/fees

Creates a fee (tax).

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to create a fee for.

Get a business' locations with the List Locations endpoint.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
id (optional)string

The fee's ID. Must be unique among all entity IDs ever provided on behalf of the merchant. You can never reuse an ID. This value can include alphanumeric characters, dashes (-), and underscores (_).

If you don't provide this value, an ID is generated by Square.

namestring

The fee's name.

ratestring

The rate of the fee, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%.

calculation_phase (optional)Fee.CalculationPhase

Whether the fee is calculated based on a payment's subtotal or total.

Default value: FEE_SUBTOTAL_PHASE

adjustment_type (optional)Fee.AdjustmentType

The type of adjustment the fee applies to a payment. Currently, this value is TAX for all fees.

Default value: TAX

applies_to_custom_amounts (optional)boolean

If true, the fee applies to custom amounts entered into Square Point of Sale that are not associated with a particular item.

Default value: true

enabled (optional)boolean

If true, the fee is applied to payments. If false, it isn't.

Default value: true

inclusion_type (optional)Fee.InclusionType

Whether the fee is ADDITIVE or INCLUSIVE.

Default value: ADDITIVE

Return Value

A Fee object that represents the created fee.

Example Request Body

{
  "name": "Sales tax",
  "rate": "0.06"
}

Example Response Body

{
  "calculation_phase": "FEE_SUBTOTAL_PHASE",
  "adjustment_type": "TAX",
  "applies_to_custom_amounts": true,
  "enabled": true,
  "inclusion_type": "ADDITIVE",
  "id": "19498df7-3fb0-4c96-8b47-860480718abk",
  "name": "Sales tax",
  "rate": "0.06",
  "type": "US_SALES_TAX"
}

List Fees

GET /v1/{location_id}/fees

Lists all of a location's fees (taxes).

Required permissions: ITEMS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to list fees for.

Get a business' locations with the List Locations endpoint.

Return Value

An array of zero or more Fee objects.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/fees

Example Response Body

[
  {
    "calculation_phase": "FEE_SUBTOTAL_PHASE",
    "adjustment_type": "TAX",
    "applies_to_custom_amounts": true,
    "enabled": true,
    "inclusion_type": "ADDITIVE",
    "id": "19498df7-3fb0-4c96-8b47-860480718abk",
    "name": "Sales tax",
    "rate": "0.06",
    "type": "US_SALES_TAX"
  },
  ...
]

Update Fee

PUT /v1/{location_id}/fees/{fee_id}

Modifies the details of an existing fee (tax).

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the fee's associated location.

Get a business' locations with the List Locations endpoint.

fee_idstring

The ID of the fee to edit.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
name (optional)string

The fee's name.

rate (optional)string

The rate of the fee, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%.

calculation_phase (optional)Fee.CalculationPhase

Whether the fee is calculated based on a payment's subtotal or total.

Default value: FEE_SUBTOTAL_PHASE

adjustment_type (optional)Fee.AdjustmentType

The type of adjustment the fee applies to a payment. Currently, this value is TAX for all fees.

Default value: TAX

applies_to_custom_amounts (optional)boolean

If true, the fee applies to custom amounts entered into Square Point of Sale that are not associated with a particular item.

Default value: true

enabled (optional)boolean

If true, the fee is applied to all appropriate items. If false, the fee is not applied at all.

Default value: true

inclusion_type (optional)Fee.InclusionType

Whether the fee is ADDITIVE or INCLUSIVE.

Default value: ADDITIVE

Return Value

A Fee object that represents the updated fee.

Example Request Body

{
  "name": "Sales tax",
  "rate": "0.06"
}

Example Response Body

{
  "calculation_phase": "FEE_SUBTOTAL_PHASE",
  "adjustment_type": "TAX",
  "applies_to_custom_amounts": true,
  "enabled": true,
  "inclusion_type": "ADDITIVE",
  "id": "19498df7-3fb0-4c96-8b47-860480718abk",
  "name": "Sales tax",
  "rate": "0.06",
  "type": "US_SALES_TAX"
}

Delete Fee

DELETE /v1/{location_id}/fees/{fee_id}

Deletes an existing fee (tax).

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the fee's associated location.

Get a business' locations with the List Locations endpoint.

fee_idstring

The ID of the fee to delete.

Return Value

If the request succeeds, the endpoint returns a 200 status code and an empty JSON object, {}.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/fees/FEE_ID

Apply Fee

PUT /v1/{location_id}/items/{item_id}/fees/{fee_id}

Associates a fee with an item, meaning the fee is automatically applied to the item in Square Point of Sale.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the fee's associated location.

Get a business' locations with the List Locations endpoint.

item_idstring

The ID of the item to add the fee to.

fee_idstring

The ID of the fee to apply.

Return Value

An Item object that represents the item with the specified fee added.

Example Request Body

https://connect.squareup.com/v1/LOCATION_ID/items/ITEM_ID/fees/FEE_ID

Remove Fee

DELETE /v1/{location_id}/items/{item_id}/fees/{fee_id}

Removes a fee assocation from an item, meaning the fee is no longer automatically applied to the item in Square Point of Sale.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the fee's associated location.

Get a business' locations with the List Locations endpoint.

item_idstring

The ID of the item to remove the fee from.

fee_idstring

The ID of the fee to remove.

Return Value

An Item object that represents the item with the specified fee removed.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/items/ITEM_ID/fees/FEE_ID

Create Page

POST /v1/{location_id}/pages

Creates a Favorites page in Square Point of Sale.

A merchant can have up to five pages, each of which has a page_index between 0 and 4, inclusive.

After you create a page, you can set the values of its cells with the Update Cell endpoint. A page doesn't appear in Square Point of Sale unless at least one of its cells has an assigned value.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to create a Favorites page for.

Get a business' locations with the List Locations endpoint.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
id (optional)string

The page's ID. Must be unique among all entity IDs ever provided on behalf of the merchant. You can never reuse an ID. This value can include alphanumeric characters, dashes (-), and underscores (_).

If you don't provide this value, an ID is generated by Square.

name (optional)string

The page's name.

page_indexnumber

The page's position in the list of pages. Must be an integer between 0 and 4, inclusive.

The endpoint returns an error if you specify a page_index that another page is already using.

Return Value

A Page object that represents the created page.

Example Request Body

{
  "name": "Lunch Items",
  "page_index": 0
}

Example Response Body

{
  "id": "c87595ae-14a6-42d7-acb6-008fc8e7ed3g",
  "name": "Lunch Items",
  "page_index": 0,
  "cells": []
}

List Pages

GET /v1/{location_id}/pages

Lists all of a location's Favorites pages in Square Point of Sale.

Required permissions: ITEMS_READ

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to list Favorites pages for.

Get a business' locations with the List Locations endpoint.

Return Value

An array of zero or more Page objects.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/pages

Example Response Body

[
  {
    "id": "c87595ae-14a6-42d7-acb6-008fc8e7ed3g",
    "name": "Lunch Items",
    "page_index": 0,
    "cells": [
      {
        "page_id": "343F7510-7214-4EB2-9B93-9DA3903327EB",
        "row": 0,
        "column": 0,
        "object_type": "ITEM",
        "object_id": "442d1344-6d2b-4238-83d0-0284dfd335d8"
      }
      ...
    ]
  },
  ...
]

Update Page

PUT /v1/{location_id}/pages/{page_id}

Modifies the details of a Favorites page in Square Point of Sale.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the Favorites page's associated location.

Get a business' locations with the List Locations endpoint..

page_idstring

The ID of the page to modify.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
name (optional)string

The page's name.

page_index (optional)number

The page's position in the merchant's list of pages. Must be an integer between 0 and 4, inclusive.

The page's index is not updated if another page already exists at the specified index.

Return Value

A Page object that represents the updated page.

Example Request Body

{
  "name": "Lunch Items",
  "page_index": 0
}

Example Response Body

{
  "id": "c87595ae-14a6-42d7-acb6-008fc8e7ed3g",
  "name": "Lunch Items",
  "page_index": 0,
  "cells": [...]
}

Delete Page

DELETE /v1/{location_id}/pages/{page_id}

Deletes an existing Favorites page and all of its cells.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the Favorites page's associated location.

Get a business' locations with the List Locations endpoint.

page_idstring

The ID of the page to delete.

Return Value

If the request succeeds, the endpoint returns a 200 status code and an empty JSON object, {}.

Example Request

https://connect.squareup.com/v1/LOCATION_ID/pages/PAGE_ID

Update Cell

PUT /v1/{location_id}/pages/{page_id}/cells

Modifies a cell of a Favorites page in Square Point of Sale.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the Favorites page's associated location.

Get a business' locations with the List Locations endpoint.

page_idstring

The ID of the page the cell belongs to.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
rownumber

The row of the cell to update. Always an integer between 0 and 4, inclusive. Row 0 is the top row.

columnnumber

The column of the cell to update. Always an integer between 0 and 4, inclusive. Column 0 is the leftmost row.

object_typePageCell.Type

The type of entity represented in the cell (ITEM, DISCOUNT, CATEGORY, or PLACEHOLDER).

object_idstring

The unique identifier of the entity to represent in the cell. Do not include if the cell's object_type is PLACEHOLDER.

placeholder_typePageCell.PlaceholderType

For a cell with an object_type of PLACEHOLDER, indicates the cell's behavior.

Return Value

A PageCell object that represents the updated cell.

Example Request Body

{
  "row": 0,
  "column": 0,
  "object_type": "ITEM",
  "object_id": "442d1344-6d2b-4238-83d0-0284dfd335d8"
}

Example Response Body

{
  "page_id": "343F7510-7214-4EB2-9B93-9DA3903327EB",
  "row": 0,
  "column": 0,
  "object_type": "ITEM",
  "object_id": "442d1344-6d2b-4238-83d0-0284dfd335d8"
}

Delete Cell

DELETE /v1/{location_id}/pages/{page_id}/cells

Deletes a cell from a Favorites page in Square Point of Sale.

Required permissions: ITEMS_WRITE

Path Parameters

NameTypeDescription
location_idstring

The ID of the Favorites page's associated location.

Get a business' locations with the List Locations endpoint.

page_idstring

The ID of the Favorites page the cell belongs to.

Request Parameters

For GET and DELETE endpoints, you provide request parameters in a query string appended to the request URL.

NameTypeDescription
rownumber

The row of the cell to clear. Always an integer between 0 and 4, inclusive. Row 0 is the top row.

columnnumber

The column of the cell to clear. Always an integer between 0 and 4, inclusive. Column 0 is the leftmost column.

Return Value

If the request succeeds, the endpoint returns a 200 status code and an empty JSON object, {}.

Example Request

https://connect.squareup.com/v1/me/pages/PAGE_ID/cells?row=3&column=4

OAuth

OAuth Overview

OAuth documentation has moved to its own reference page.

Batching

Submit Batch

POST /v1/batch

Lets you batch multiple requests to other Connect API endpoints into a single request. This endpoint's response is an array that contains the response for each batched request.

You don't need to provide an access token in the header of your request to the Submit Batch endpoint. Instead, you provide an access_token parameter for each request included in the batch.

Note the following when using the Submit Batch endpoint:

  • You cannot include more than 30 requests in a single batch.
  • Recursive requests to the Submit Batch endpoint are not allowed (i.e., none of the requests included in a batch can itself be a request to this endpoint).
  • There is no guarantee of the order in which batched requests are performed.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
requestsBatchRequest[]

The requests to perform.

Return Value

An array of BatchResponse objects corresponding to requests. The index of each response in the array matches the index of the corresponding request.

Example Request Body

{
  "requests": [
    {
      "method": "POST",
      "relative_path": "/v1/LOCATION_ID/categories",
      "access_token": "ACCESS_TOKEN",
      "body": {
        "name": "Beverages"
      },
      "request_id": "MyRequestID"
    }
  ]
}

Example Response Body

[
  {
    "status_code": 200,
    "body": {
      "id": "36ac7016-3a4e-4934-81f1-9057ac613f2y",
      "name": "Beverages"
    },
    "request_id": "MyRequestID"
  }
]

API Webhooks

Webhooks Overview

The Square Connect API provides webhooks that can notify your application as certain events occur (such as when a payment is created or updated). Notifications are typically sent within sixty seconds of the associated event.

The Connect API can send webhook notifications when the following events occur:

  • A payment is created or updated
  • An item variation's inventory is updated
  • An employee timecard is created or updated

Quick setup

Subscribe to new payment events on your own Square account with the following steps:

  1. In a new tab, go to requestcatcher.com and create a subdomain. You'll use this page to listen for test webhook notifications.
  2. Open your application's settings from the application dashboard and select the Webhooks tab.
  3. Click Enable Webhooks if it isn't already enabled.
  4. In the Notification URL field, specify the URL of your requestcatcher.com page and click Save.
  5. Subscribe to webhook notifications from your own Square account by sending the following curl request to the Update Webhooks endpoint (providing your personal access token and location ID where indicated):
curl -X PUT -H "Authorization: Bearer PERSONAL_ACCESS_TOKEN" -H "Content-Type: application/json" -d "[\"PAYMENT_UPDATED\"]" https://connect.squareup.com/v1/LOCATION_ID/webhooks

Open the Square Point of Sale app on your device and simulate a cash payment. Within 60 seconds, your requestcatcher.com page should receive a POST request with a JSON body similar to the following:

{
  "merchant_id": "18YC4JBH91E1H",
  "location_id": "JGHJ0343",
  "event_type": "PAYMENT_UPDATED",
  "entity_id": "Jq74mCczmFXk1tC10GB"
}

You can provide the value of entity_id to the Retrieve Payment endpoint to get the full details of the payment. Make sure to provide the value of location_id in the path of your request.

Once you get webhooks up and running, be sure to set your Notification URL field to a URL that your application is listening on.

A code sample on Github (Python | Ruby | PHP | Java) demonstrates a simple server that listens for webhook notifications.

Subscribing to webhook notifications from other merchants

If you're developing an application for other merchants, your application can receive webhook notifications from each of those merchants. In order to do so, your application must subscribe to each merchant location by sending PUT requests to the Update Webhooks endpoint. The body of each request is an array of the event types you want to receive notifications for, such as the following:

["PAYMENT_UPDATED", "INVENTORY_UPDATED"]

Providing this array for a given location overwrites all prior arrays you've provided for the same location.

If you want to stop receiving all notifications for a particular location, you can provide an empty array, [].

You can see which webhooks you've enabled for a location by sending a GET request to the List Webhooks endpoint.

Notification format

Webhooks notify your application by sending a POST request to a URL you specify on the application dashboard. The request's body is a JSON object with the following format:

{
  "merchant_id": "JGHJ0343",
  "event_type": "PAYMENT_UPDATED",
  "entity_id": "Jq74mCczmFXk1tC10GB"
}
  • merchant_id indicates the merchant that triggered the event.
  • event_type indicates the type of event that occurred. See WebhookEventType for possible values.
  • entity_id is the id of the entity associated with the event, if applicable (in this case, the id of the updated payment).

You can provide the value of entity_id to the corresponding Retrieve endpoint (such as Retrieve Payment) to get the entity's full details.

This code sample demonstrates a basic web server that listens for webhook notifications and retrieves associated payments.

Checking for new entities

The PAYMENT_UPDATED and TIMECARD_UPDATED events occur both when a new entity of the corresponding type is created and when the details of an existing entity are updated (such as when a refund is issued).

To determine whether a webhook notification indicates a new entity, you can maintain a list of a merchant's existing entity ids. If a notification's entity_id matches any id in the list, the entity is not new. You can also check the entity's created_at field to see whether it was created since the last time you sent a request to the corresponding List endpoint.

Webhook availability

Square attempts to send one notification to your application per applicable event. If a notification fails for any reason, Square does not reattempt it. If webhooks become unavailable for a period of time, notifications that would have been sent during that period are not sent, even at a later time.

You should use List endpoints (such as List Payments) periodically to confirm that you have received notifications for all of the events you expect.

Webhook permissions

Your application must have the required permission scope to enable webhook notifications. Different event types require different permissions:

Event typePermission
PAYMENT_UPDATEDPAYMENTS_READ
INVENTORY_UPDATEDITEMS_READ
TIMECARD_UPDATEDTIMECARDS_READ

If you attempt to request an event type that you don't have the required permission for, your request to the Update Webhooks endpoint fails with an error.

If your application later loses a permission required for a particular event type, it no longer receives notifications for that event type.

Validating notifications

All webhook notifications from Square include an X-Square-Signature header. The value of this header is the HMAC-SHA1 signature of a string consisting of your webhook notification URL followed immediately by the body of the request (no whitespace). The signature is signed with your webhook signature key, available on the application dashboard.

For example, this string:

http://www.example.com{"merchant_id":"JGHJ0343","event_type":"PAYMENT_UPDATED","entity_id":"Jq74mCczmFXk1tC10GB"}

Signed with this signature key:

EXAMPLE_SECRET_123

Has the following signature:

DBP9woNqJpO4d4/ZFE7xveLIGPU=

You can compute the value of the signature in your application to ensure it matches the signature provided in the request.

The is_valid_callback function of this code sample demonstrates validating webhook notifications by their signature.

List Webhooks

GET /v1/{location_id}/webhooks

Lists which types of events trigger webhook notifications for a particular location.

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to list webhook notification types for.

Return Value

An array of WebhookEventType values.

Example Request

https://connect.squareup.com/v1/me/webhooks

Example Response Body

["PAYMENT_UPDATED"]

Update Webhooks

PUT /v1/{location_id}/webhooks

Sets which types of events trigger webhook notifications for a location.

Simply provide a JSON array of the event types you want notifications for in your request body (see Example Requests below).

Path Parameters

NameTypeDescription
location_idstring

The ID of the location to update webhook preferences for.

Return Value

An array of WebhookEventType values that match the values you provided.

Example Request Body

["PAYMENT_UPDATED"]

Example Response Body

["PAYMENT_UPDATED"]

Subscription Management

Subscriptions Overview

Your application can have one or more paid subscription plans associated with it. Merchants can sign up for one of these subscription plans at the same time they authorize your application. You can use a merchant's current subscription plan and status to control their access to different features of your application.

Note that these endpoints pertain to merchants subscribing to a developer application, not to buyers subscribing to a merchant's goods or services.

Billing basics

Subscriptions are billed on a monthly basis. Merchants are charged subscription fees on the first of the month.

Application owners receive 70% of collected subscription fees.

When a merchant signs up for a subscription plan, they immediately pay the first month's fee, prorated for the number of days remaining in the billing period.

If a merchant's monthly subscription payment fails for any reason (such as due to an invalid payment method), the merchant enters a fifteen-day grace period, during which the subscription should still be considered active.

If a merchant fails to update their payment information by the end of the grace period, their subscription is automatically canceled.

A merchant can cancel an active subscription at any time. Depending on how the subscription is canceled, it might remain active until the current billing period ends. See Canceling a subscription for details.

If your application has more than one subscription plan (for example, a basic plan and a premium plan), a merchant can switch between them at any time.

If a merchant switches to a plan with a lower subscription fee, the new fee amount takes effect at the beginning of the next billing period.

If a merchant switches to a plan with a higher subscription fee, the merchant immediately pays the fee difference, prorated for the number of days remaining in the current billing period. For example, if a merchant switches from a $10 plan to a $20 plan halfway through a billing period, they pay an additional $5 for the billing period.

Creating a subscription plan

Currently, you must work directly with Square to create subscription plans for your application. Each subscription plan has its own name, fee amount, and plan_id.

There is a separate instance of each subscription plan for each country you release your application in. For example, if your application has two subscription levels (basic and premium) and it launches in two countries, you have a total of four subscription plans. This lets you set each plan's price on a per-country basis.

You can view the details of all of your subscription plans with the List Subscription Plans endpoint.

Signing up a merchant for a subscription plan

Merchants sign up for a subscription plan in your application's authorization flow:

  1. When you direct a merchant to the Permissions form, you can include a plan_id as a URL parameter.
  2. After the merchant signs in and authorizes your app, they're directed to a second form where they can provide their payment details and approve the subscription.
  3. The result of the entire authorization flow is passed along to the redirect_uri you provided in your request to the Permissions form.

See OAuth Overview for more information on the OAuth process.

Changing a merchant's subscription plan

If a merchant wants to switch to a different subscription plan, you can direct them back to the Permissions form and include the plan_id of the new plan as a URL parameter. After signing in, the merchant is prompted to approve the new plan.

Canceling a subscription

There are a few different ways to cancel a merchant's subscription:

From the Permissions form

You can direct the merchant to the Permissions form and include a plan_id URL parameter with no value (plan_id=). After signing in, the merchant is prompted to approve the cancellation of their current subscription.

If a subscription is canceled this way, it remains active until the end of the current billing period.

Canceling a subscription this way does not affect your application's access to the merchant's data.

With the Revoke Token endpoint

If you revoke a merchant's access token with the Revoke Token endpoint, any subscription they have with your application is canceled immediately (it does not remain active until the end of the billing period). Your application loses all access to the merchant's data.

From the merchant dashboard

Merchants can revoke your application's access to their data from the merchant dashboard. If they do, any subscription they have with your application is canceled immediately (it does not remain active until the end of the billing period).

Getting a merchant's subscription status

You can use the List Subscriptions endpoint to get a single merchant's subscription information, or to obtain all of the subscriptions associated with your application.

To get subscription information associated with a single merchant, include the merchant's merchant_id as a parameter in your request. Note that your request still might return more than one Subscription object, if the merchant has ever switched plans or subscribed to your application more than once.

Subscription objects returned by the List Subscriptions endpoint have a status field that indicates whether the subscription is active.

Subscriptions with any of the following status values are considered active:

  • ACTIVE
  • IN_GRACE

Subscriptions with any of the following status values are considered inactive:

  • CANCELED
  • TERMINATED

See Subscription.Status for details on what each of these statuses indicates.

Getting a subscription's payment history

Subscription objects returned by the Retrieve Subscription endpoint include a fees field. This is an array of SubscriptionFee objects that each represent a single subscription fee charged to the merchant.

SubscriptionFee objects have a status field that indicates the status of the payment. See SubscriptionFee.Status for details on what each of these statuses indicates.

List Subscriptions

GET /oauth2/clients/{client_id}/subscriptions

Lists subscriptions that have been created for an application. You can look up subscription information for a single merchant by providing the merchant_id parameter to this endpoint.

Subscription objects returned by this endpoint do not include the fees field, which lists the subscription's payment history. To get a particular subscription's payment history, use the Retrieve Subscription endpoint.

Important: The Authorization header you provide to this endpoint must have the following format:

Authorization: Client APPLICATION_SECRET

Replace APPLICATION_SECRET with your application's secret, available from the application dashboard.

Path Parameters

NameTypeDescription
client_idstring

Your application's ID, available from the application dashboard.

Request Parameters

For GET and DELETE endpoints, you provide request parameters in a query string appended to the request URL.

NameTypeDescription
merchant_id (optional)string

If you provide this parameter, the endpoint returns only subscription information for the specified merchant.

You can get a merchant's ID with the Retrieve Merchant endpoint.

limitnumber

The maximum number of subscriptions to return in a single response. This value cannot exceed 200.

Default value: 100

Return Value

An array of zero or more Subscription objects.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/oauth2/clients/YOUR_APPLICATION_ID/subscriptions

Example Response Body

[
  {
    "status": "ACTIVE",
    "payment_method": "CARD",
    "service_start_date": "2014-08-04",
    "id": "f34281ba9576",
    "merchant_id": "JGHJ0343",
    "plan_id": "myapp_basic",
    "fee_base_money": {
      "amount": 1500,
      "currency_code": "USD"
    }
  },
  ...
]

Retrieve Subscription

GET /oauth2/clients/{client_id}/subscriptions/{subscription_id}

Provides comprehensive information for a single subscription, including its payment history.

Important: The Authorization header you provide to this endpoint must have the following format:

Authorization: Client APPLICATION_SECRET

Replace APPLICATION_SECRET with your application's secret, available from the application dashboard.

Path Parameters

NameTypeDescription
client_idstring

Your application's ID, available from the application dashboard.

subscription_idstring

The subscription's ID.

Return Value

A Subscription object that describes the requested subscription.

Example Request

https://connect.squareup.com/oauth2/clients/YOUR_APPLICATION_ID/subscriptions/f34281ba9576

Example Response Body

{
  "status": "ACTIVE",
  "payment_method": "CARD",
  "service_start_date": "2014-08-04",
  "id": "f34281ba9576",
  "merchant_id": "JGHJ0343",
  "plan_id": "myapp_basic",
  "fee_base_money": {
    "amount": 1500,
    "currency_code": "USD"
  },
  "fees": [
    {
      "fee_date": "2014-08-04",
      "fee_status": "PAID",
      "fee_base_money": {
        "amount": 1500,
        "currency_code": "USD"
      },
      "fee_tax_money": {
        "amount": 0,
        "currency_code": "USD"
      },
      "fee_total_money": {
        "amount": 0,
        "currency_code": "USD"
      }
    }
  ]
}

List Subscription Plans

GET /oauth2/clients/{client_id}/plans

Provides information for all of an application's subscription plans.

Important: The Authorization header you provide to this endpoint must have the following format:

Authorization: Client APPLICATION_SECRET

Replace APPLICATION_SECRET with your application's secret, available from the application dashboard.

Path Parameters

NameTypeDescription
client_idstring

Your application's ID, available from the application dashboard.

Return Value

An array of zero or more SubscriptionPlan objects.

This endpoint might paginate its results.

Example Request

https://connect.squareup.com/oauth2/clients/YOUR_APPLICATION_ID/plans

Example Response Body

[
  {
    "id": "myapp_basic",
    "name": "Basic",
    "fee_base_money":{
      "amount": 1500,
      "currency_code": "USD"
    },
    "country_code": "US"
  }
]

Retrieve Subscription Plan

GET /oauth2/clients/{client_id}/plans/{plan_id}

Provides comprehensive information for a single subscription plan.

Important: The Authorization header you provide to this endpoint must have the following format:

Authorization: Client APPLICATION_SECRET

Replace APPLICATION_SECRET with your application's secret, available from the application dashboard.

Path Parameters

NameTypeDescription
client_idstring

Your application's ID, available from the application dashboard.

plan_idstring

The subscription plan's ID.

Return Value

A SubscriptionPlan object that describes the requested subscription.

Example Request

https://connect.squareup.com/oauth2/clients/YOUR_APPLICATION_ID/plans/myapp_basic

Example Response Body

{
  "id": "myapp_basic",
  "name": "Basic",
  "fee_base_money":{
    "amount": 1500,
    "currency_code": "USD"
  },
  "country_code": "US"
}

Appendix

Connect API Data Types

BankAccount

Represents a merchant's bank account.

Fields

NameTypeDescription
idstring

The bank account's Square-issued ID.

merchant_idstring

The Square-issued ID of the merchant associated with the bank account.

bank_namestring

The name of the bank that manages the account.

namestring

The name associated with the bank account.

typeBankAccount.Type

The bank account's type (for example, savings or checking).

routing_numberstring

The bank account's routing number.

account_number_suffixstring

The last few digits of the bank account number.

currency_codestring

The currency code of the currency associated with the bank account, in ISO 4217 format. For example, the currency code for US dollars is USD.

BatchRequest

Represents a single request included in a call to the Submit Batch endpoint.

Fields

NameTypeDescription
methodRequestMethod

The HTTP method of the request (DELETE, GET, POST, or PUT).

relative_pathstring

The path of the request's endpoint, relative to https://connect.squareup.com.

For example, this value is /v1/MERCHANT_ID/payments for the List Payments endpoint (with the proper merchant ID).

For GET and DELETE requests, include any request parameters in a query string appended to the path (for example, /v1/MERCHANT_ID/payments?order=DESC).

access_tokenstring

The access token to use for the request. This can be a personal access token or an access token generated with the OAuth API.

bodyobject

The body of the request, if any. Include parameters for POST and PUT requests here.

request_idstring

An optional identifier for the request, returned in the request's corresponding BatchResponse.

BatchResponse

Represents the response for a request included in a call to the Submit Batch endpoint.

Fields

NameTypeDescription
status_codenumber

The response's HTTP status code.

headersobject

Contains any important headers for the response, indexed by header name. For example, if the response includes a pagination header, the header's value is available from headers["Link"].

bodyobject

The body of the response, if any.

request_idstring

The value you provided for request_id in the corresponding BatchRequest, if any.

Coordinates

Represents geographic coordinates.

Fields

NameTypeDescription
latitudenumber

The latitude coordinate, in degrees.

longitudenumber

The longitude coordinate, in degrees.

CashDrawerEvent

Represents an event (such as a payment or refund) that involved opening the cash drawer during a cash drawer shift.

Fields

NameTypeDescription
idstring

The event's unique ID.

employee_idstring

The ID of the employee that created the event.

event_typeCashDrawerEvent.Type

The type of event that occurred, such as CASH_TENDER_PAYMENT or CASH_TENDER_REFUND.

event_moneyMoney

The amount of money that was added to or removed from the cash drawer because of the event. This value can be positive (for added money) or negative (for removed money).

created_atstring

The time when the event occurred, in ISO 8601 format.

descriptionstring

An optional description of the event, entered by the employee that created it.

CashDrawerShift

Represents all cash drawer activity that takes place during a single cash drawer shift.

Fields

NameTypeDescription
idstring

The shift's unique ID.

cash_drawer_stateCashDrawerShift.State

The shift's current state (OPEN, ENDED, or CLOSED).

opened_atstring

The time when the shift began, in ISO 8601 format.

ended_atstring

The time when the shift ended, in ISO 8601 format.

closed_atstring

The time when the shift was closed, in ISO 8601 format.

employee_idsstring[]

The IDs of all employees that were logged into Square Point of Sale at some point during the cash drawer shift.

opening_employee_idstring

The ID of the employee that started the cash drawer shift.

ending_employee_idstring

The ID of the employee that ended the cash drawer shift.

closing_employee_idstring

The ID of the employee that closed the cash drawer shift by auditing the cash drawer's contents.

descriptionstring

An optional description of the shift, entered by the employee that ended it.

starting_cash_moneyMoney

The amount of money in the cash drawer at the start of the shift.

cash_payment_moneyMoney

The amount of money added to the cash drawer from cash payments.

cash_refunds_moneyMoney

The amount of money removed from the cash drawer from cash refunds. This value is always negative or zero.

cash_paid_in_moneyMoney

The amount of money added to the cash drawer for reasons other than cash payments.

cash_paid_out_moneyMoney

The amount of money removed from the cash drawer for reasons other than cash refunds.

expected_cash_moneyMoney

The amount of money that should be in the cash drawer at the end of the shift, based on the shift's other money amounts.

closed_cash_moneyMoney

The amount of money found in the cash drawer at the end of the shift by an auditing employee.

deviceDevice

The device running Square Point of Sale that was connected to the cash drawer.

eventsCashDrawerEvent[]

All of the events (payments, refunds, and so on) that involved the cash drawer during the shift.

Category

Represents an item category.

Fields

NameTypeDescription
idstring

The category's unique ID.

namestring

The category's name.

Device

Represents a device running Square Point of Sale.

Fields

NameTypeDescription
namestring

The device's merchant-specified name.

idstring

The device's Square-issued ID.

Discount

Represents a discount that can be applied to a payment. A discount can be either a percentage or a flat amount. You can determine a particular discount's type by checking which of rate or amount_money is included in the object.

Fields

NameTypeDescription
idstring

The discount's unique ID.

namestring

The discount's name.

ratestring

The rate of the discount, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%. This rate is 0 if discount_type is VARIABLE_PERCENTAGE.

This field is not included for amount-based discounts.

amount_moneyMoney

The amount of the discount. This amount is 0 if discount_type is VARIABLE_AMOUNT.

This field is not included for rate-based discounts.

discount_typeDiscount.Type

Indicates whether the discount is a FIXED value or entered at the time of sale.

pin_requiredboolean

Indicates whether a mobile staff member needs to enter their PIN to apply the discount to a payment.

colorItem.Color

The color of the discount's display label in Square Point of Sale, if not the default color.

The default color is 9da2a6.

Employee

Represents one of a business' employees.

Fields

NameTypeDescription
idstring

The employee's unique ID.

first_namestring

The employee's first name.

last_namestring

The employee's last name.

role_idsstring[]

The ids of the employee's associated roles. Currently, you can specify only one or zero roles per employee.

authorized_location_idsstring[]

The IDs of the locations the employee is allowed to clock in at.

emailstring

The employee's email address.

You cannot edit this value with the Connect API. You can only set its initial value when creating an employee with the Create Employee endpoint.

statusEmployee.Status

Whether the employee is ACTIVE or INACTIVE. Inactive employees cannot sign in to Square Point of Sale.

Merchants update this field from the Square Dashboard. You cannot modify it with the Connect API.

external_idstring

An ID the merchant can set to associate the employee with an entity in another system.

You cannot set this value with the Connect API.

created_atstring

The time when the employee entity was created, in ISO 8601 format.

updated_atstring

The time when the employee entity was most recently updated, in ISO 8601 format.

EmployeeRole

Represents a role that can be assigned to one or more employees. An employee's role indicates which permissions they have.

Fields

NameTypeDescription
idstring

The role's unique ID.

namestring

The role's merchant-defined name.

permissionsEmployeeRole.Permission[]

The permissions that the role has been granted.

is_ownerboolean

If true, employees with this role have all permissions, regardless of the values indicated in permissions.

created_atstring

The time when the role was created, in ISO 8601 format.

updated_atstring

The time when the role was most recently updated, in ISO 8601 format.

Fee

Represents a tax or other fee that can be applied to a payment.

Fields

NameTypeDescription
idstring

The fee's unique ID.

namestring

The fee's name.

ratestring

The rate of the fee, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%.

calculation_phaseFee.CalculationPhase

Forthcoming.

adjustment_typeFee.AdjustmentType

The type of adjustment the fee applies to a payment. Currently, this value is TAX for all fees.

applies_to_custom_amountsboolean

If true, the fee applies to custom amounts entered into Square Point of Sale that are not associated with a particular item.

enabledboolean

If true, the fee is applied to all appropriate items. If false, the fee is not applied at all.

inclusion_typeFee.InclusionType

Whether the fee is ADDITIVE or INCLUSIVE.

typeFee.Type

In countries with multiple classifications for sales taxes, indicates which classification the fee falls under. Currently relevant only to Canadian merchants.

GlobalAddress

A generic representation of a physical address.

Fields

NameTypeDescription
address_line_1string

The first line of the address.

Fields that start with address_line provide the address's most specific details, like street number, street name, and building name. They do not provide less specific details like city, state/province, or country (these details are provided in other fields).

address_line_2string

The second line of the address, if any.

address_line_3string

The third line of the address, if any.

address_line_4string

The fourth line of the address, if any.

address_line_5string

The fifth line of the address, if any.

localitystring

The city or town of the address.

sublocalitystring

A civil region within the address's locality, if any.

sublocality_1string

A civil region within the address's sublocality, if any.

sublocality_2string

A civil region within the address's sublocality_1, if any.

sublocality_3string

A civil region within the address's sublocality_2, if any.

sublocality_4string

A civil region within the address's sublocality_3, if any.

sublocality_5string

A civil region within the address's sublocality_4, if any.

administrative_district_level_1string

A civil entity within the address's country. In the United States, this is the state.

administrative_district_level_2string

A civil entity within the address's administrative_district_level_1, if any. In the United States, this is the county.

administrative_district_level_3string

A civil entity within the address's administrative_district_level_2, if any.

postal_codestring

The address's postal code.

country_codestring

The address's country, in ISO 3166-1-alpha-2 format.

address_coordinatesCoordinates

The coordinates of the address.

InventoryEntry

Represents inventory information for one of a merchant's item variations.

Fields

NameTypeDescription
variation_idstring

The variation that the entry corresponds to.

quantity_on_handnumber

The current available quantity of the item variation.

Item

Represents a merchant's item.

Fields

NameTypeDescription
idstring

The item's unique ID.

namestring

The item's name.

descriptionstring

The item's description, if any.

typeItem.Type

The item's type. This value is NORMAL for almost all items.

abbreviationstring

The text of the item's display label in Square Point of Sale. This value is present only if an abbreviation other than the default has been set.

colorItem.Color

The color of the item's display label in Square Point of Sale, if not the default color.

The default color is 9da2a6.

visibilityItem.Visibility

Indicates whether the item is viewable in the merchant's online store (PUBLIC) or PRIVATE.

available_onlineboolean

If true, the item is available for purchase from the merchant's online store.

master_imageItemImage

The item's master image, if any.

categoryCategory

The category the item belongs to, if any.

variationsItemVariation[]

The item's variations.

modifier_listsModifierList[]

The modifier lists that apply to the item, if any.

feesFee[]

The fees that apply to the item, if any.

taxableboolean

Deprecated. This field is not used.

ItemImage

Represents an image of an item.

Fields

NameTypeDescription
idstring

The image's unique ID.

urlstring

The image's publicly accessible URL.

ItemVariation

Represents a variation of an Item. Every item has at least one variation.

Fields

NameTypeDescription
idstring

The item variation's unique ID.

namestring

The item variation's name.

item_idstring

The ID of the variation's associated item.

ordinalnumber

Indicates the variation's list position when displayed in Square Point of Sale and the merchant dashboard. If more than one variation for the same item has the same ordinal value, those variations are displayed in alphabetical order.

An item's variation with the lowest ordinal value is displayed first.

pricing_typeItemVariation.PricingType

Indicates whether the item variation's price is fixed or determined at the time of sale.

price_moneyMoney

The item variation's price, if any.

skustring

The item variation's SKU, if any.

track_inventoryboolean

If true, inventory tracking is active for the variation.

inventory_alert_typeInventoryAlertType

Indicates whether the item variation displays an alert when its inventory quantity is less than or equal to its inventory_alert_threshold.

inventory_alert_thresholdnumber

If the inventory quantity for the variation is less than or equal to this value and inventory_alert_type is LOW_QUANTITY, the variation displays an alert in the merchant dashboard.

This value is always an integer.

user_datastring

Arbitrary metadata associated with the variation. Cannot exceed 255 characters.

Merchant

Represents a Square merchant account.

Fields

NameTypeDescription
idstring

The merchant account's unique identifier.

namestring

The name associated with the merchant account.

emailstring

The email address associated with the merchant account.

account_typeMerchant.AccountType

Indicates whether the merchant account corresponds to a single-location account (LOCATION) or a business account (BUSINESS). This value is almost always LOCATION. See Structure of a Square business for more information.

account_capabilitiesMerchant.AccountCapability[]

Capabilities that are enabled for the merchant's Square account. Capabilities that are not listed in this array are not enabled for the account. Currently there is only one capability, CREDIT_CARD_PROCESSING.

country_codestring

The country associated with the merchant account, in ISO 3166-1-alpha-2 format.

language_codestring

The language associated with the merchant account, in BCP 47 format.

currency_codestring

The currency associated with the merchant account, in ISO 4217 format. For example, the currency code for US dollars is USD.

business_namestring

The name of the merchant's business.

business_addressGlobalAddress

The address of the merchant's business.

business_phonePhoneNumber

The phone number of the merchant's business.

business_typeMerchant.BusinessType

The type of business operated by the merchant.

shipping_addressGlobalAddress

The merchant's shipping address.

location_detailsMerchantLocationDetails

Additional information for a single-location account specified by its associated business account, if it has one.

Never included in Merchant objects with the account_typeBUSINESS.

market_urlstring

The URL of the merchant's online store.

MerchantLocationDetails

Represents additional details for a single-location account as specified by its parent business.

Fields

NameTypeDescription
nicknamestring

The nickname assigned to the single-location account by the parent business. This value appears in the parent business' multi-location dashboard.

ModifierList

Represents an item modifier list.

Fields

NameTypeDescription
idstring

The modifier list's unique ID.

namestring

The modifier list's name.

selection_typeModifierList.SelectionType

Indicates whether MULTIPLE options or a SINGLE option from the modifier list can be applied to a single item.

modifier_optionsModifierOption[]

The options included in the modifier list.

ModifierOption

Represents an item modifier option.

Fields

NameTypeDescription
idstring

The modifier option's unique ID.

namestring

The modifier option's name.

price_moneyMoney

The modifier option's price.

on_by_defaultboolean

If true, the modifier option is the default option in a modifier list for which selection_type is SINGLE.

ordinalnumber

Indicates the modifier option's list position when displayed in Square Point of Sale and the merchant dashboard. If more than one modifier option in the same modifier list has the same ordinal value, those options are displayed in alphabetical order.

A modifier list's option with the lowest ordinal value is displayed first.

modifier_list_idstring

The ID of the modifier list the option belongs to.

Money

Represents an amount of money. When you provide this object in a request, currency_code must match the currency associated with the merchant's Square account.

Fields

NameTypeDescription
amountnumber

The amount of money, in the smallest unit of the applicable currency. For US dollars, this value is in cents.

This value is always an integer.

currency_codeMoney.CurrencyCode

The type of currency involved in the current payment, in ISO 4217 format. For example, the currency code for US dollars is USD.

Order

Represents an order from a merchant's online store.

Fields

NameTypeDescription
idstring

The order's unique identifier.

stateOrder.State

The order's current state, such as OPEN or COMPLETED.

buyer_emailstring

The email address of the order's buyer.

recipient_namestring

The name of the order's buyer.

recipient_phone_numberstring

The phone number to use for the order's delivery.

shipping_addressGlobalAddress

The address to ship the order to.

subtotal_moneyMoney

The amount of all items purchased in the order, before taxes and shipping.

total_shipping_moneyMoney

The shipping cost for the order.

total_tax_moneyMoney

The total of all taxes applied to the order.

total_price_moneyMoney

The total cost of the order.

total_discount_moneyMoney

The total of all discounts applied to the order.

created_atstring

The time when the order was created, in ISO 8601 format.

updated_atstring

The time when the order was last modified, in ISO 8601 format.

expires_atstring

The time when the order expires if no action is taken, in ISO 8601 format.

payment_idstring

The unique identifier of the payment associated with the order.

buyer_notestring

A note provided by the buyer when the order was created, if any.

completed_notestring

A note provided by the merchant when the order's state was set to COMPLETED, if any.

refunded_notestring

A note provided by the merchant when the order's state was set to REFUNDED, if any.

canceled_notestring

A note provided by the merchant when the order's state was set to CANCELED, if any.

tenderTender

The tender used to pay for the order.

order_historyOrderHistoryEntry[]

The history of actions associated with the order.

promo_codestring

The promo code provided by the buyer, if any.

btc_receive_addressstring

For Bitcoin transactions, the address that the buyer sent Bitcoin to.

btc_price_satoshinumber

For Bitcoin transactions, the price of the buyer's order in satoshi (100 million satoshi equals 1 BTC).

OrderHistoryEntry

Represents a prior action performed on an online store order.

Fields

NameTypeDescription
actionOrderHistoryEntry.ActionType

The type of action performed on the order.

created_atstring

The time when the action was performed, in ISO 8601 format.

Page

Represents a Favorites page in the iPad version of Square Point of Sale.

Fields

NameTypeDescription
idstring

The page's unique identifier.

namestring

The page's name, if any.

page_indexnumber

The page's position in the merchant's list of pages. Always an integer between 0 and 4, inclusive.

cellsPageCell[]

The cells included on the page.

PageCell

Represents a cell of a Page.

Fields

NameTypeDescription
page_idstring

The unique identifier of the page the cell is included on.

rownumber

The row of the cell. Always an integer between 0 and 4, inclusive.

columnnumber

The column of the cell. Always an integer between 0 and 4, inclusive.

object_typePageCell.Type

The type of entity represented in the cell (ITEM, DISCOUNT, CATEGORY, or PLACEHOLDER).

object_idstring

The unique identifier of the entity represented in the cell. Not present for cells with an object_type of PLACEHOLDER.

placeholder_typePageCell.PlaceholderType

For a cell with an object_type of PLACEHOLDER, this value indicates the cell's special behavior.

Payment

Represents a payment taken by a Square merchant.

Fields

NameTypeDescription
idstring

The payment's unique identifier.

merchant_idstring

The unique identifier of the merchant that took the payment.

created_atstring

The time when the payment was created, in ISO 8601 format.

creator_idstring

The unique identifier of the Square account that took the payment.

This value can differ from merchant_id if the merchant has mobile staff.

deviceDevice

The device that took the payment.

payment_urlstring

The URL of the payment's detail page in the merchant dashboard. The merchant must be signed in to the merchant dashboard to view this page.

receipt_urlstring

The URL of the receipt for the payment.

Note that for split tender payments, this URL corresponds to the receipt for the first tender listed in the payment's tender field. Each Tender object has its own receipt_url field you can use to get the other receipts associated with a split tender payment.

inclusive_tax_moneyMoney

The sum of all inclusive taxes associated with the payment.

additive_tax_moneyMoney

The sum of all additive taxes associated with the payment.

tax_moneyMoney

The total of all taxes applied to the payment.

This is always the sum of inclusive_tax_money and additive_tax_money.

tip_moneyMoney

The total of all tips applied to the payment.

discount_moneyMoney

The total of all discounts applied to the payment.

This value is always 0 or negative.

total_collected_moneyMoney

The total amount of money collected from the buyer for the payment.

processing_fee_moneyMoney

The total of all processing fees collected by Square for the payment.

This value is always 0 or negative.

net_total_moneyMoney

The amount to be deposited into the merchant's bank account for the payment.

This is always the sum of total_collected_money and processing_fee_money (note that processing_fee_money is always negative or 0).

refunded_moneyMoney

The total of all refunds applied to the payment.

inclusive_taxPaymentTax[]

All of the inclusive taxes associated with the payment.

additive_taxPaymentTax[]

All of the additive taxes associated with the payment.

tenderTender[]

The form(s) of tender provided by the buyer for the payment.

refundsRefund[]

All of the refunds applied to the payment.

itemizationsPaymentItemization[]

The items purchased in the payment.

PaymentDiscount

Represents a discount applied to an itemization in a payment.

Fields

NameTypeDescription
namestring

The discount's name.

applied_moneyMoney

The amount of money that this discount adds to the payment (note that this value is always negative or zero).

discount_idstring

The ID of the applied discount, if available. Discounts applied in older versions of Square Point of Sale might not have an ID.

PaymentItemDetail

Represents details of an item purchased in a payment.

Fields

NameTypeDescription
category_namestring

The name of the item's merchant-defined category, if any.

skustring

The item's merchant-defined SKU, if any.

item_idstring

The unique ID of the item purchased, if any.

item_variation_idstring

The unique ID of the item variation purchased, if any.

PaymentItemization

Represents an item, custom monetary amount, or other entity purchased as part of a payment.

Fields

NameTypeDescription
namestring

The item's name.

quantitynumber

The quantity of the item purchased. This can be a decimal value.

itemization_typePaymentItemization.Type

The type of purchase that the itemization represents, such as an ITEM or CUSTOM_AMOUNT.

item_detailPaymentItemDetail

Details of the item, including its unique identifier and the identifier of the item variation purchased.

notesstring

Notes entered by the merchant about the item at the time of payment, if any.

item_variation_namestring

The name of the item variation purchased, if any.

total_moneyMoney

The total cost of the item, including all taxes and discounts.

single_quantity_moneyMoney

The cost of a single unit of this item.

gross_sales_moneyMoney

The total cost of the itemization and its modifiers, not including taxes or discounts.

discount_moneyMoney

The total of all discounts applied to the itemization. This value is always negative or zero.

net_sales_moneyMoney

The sum of gross_sales_money and discount_money.

taxesPaymentTax[]

All taxes applied to this itemization.

discountsPaymentDiscount[]

All discounts applied to this itemization.

modifiersPaymentModifier[]

All modifier options applied to this itemization.

PaymentModifier

Represents a modifier option applied to an itemization in a payment.

Fields

NameTypeDescription
namestring

The modifier option's name.

applied_moneyMoney

The amount of money that this modifier option adds to the payment.

modifier_option_idstring

The ID of the applied modifier option, if available. Modifier options applied in older versions of Square Point of Sale might not have an ID.

PaymentTax

Represents a single tax applied to a payment.

Fields

NameTypeDescription
namestring

The merchant-defined name of the tax.

applied_moneyMoney

The amount of money that this tax adds to the payment.

ratestring

The rate of the tax, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%.

inclusion_typeFee.InclusionType

Whether the tax is an ADDITIVE tax or an INCLUSIVE tax.

fee_idstring

The ID of the tax, if available. Taxes applied in older versions of Square Point of Sale might not have an ID.

PhoneNumber

Represents a phone number.

Fields

NameTypeDescription
calling_codestring

The phone number's international calling code. For US phone numbers, this value is +1.

numberstring

The phone number.

Refund

Represents a refund initiated by a Square merchant.

Fields

NameTypeDescription
typeRefund.Type

The type of refund (FULL or PARTIAL).

reasonstring

The merchant-specified reason for the refund.

refunded_moneyMoney

The amount of money refunded. This amount is always negative.

created_atstring

The time when the merchant initiated the refund for Square to process, in ISO 8601 format.

processed_atstring

The time when Square processed the refund on behalf of the merchant, in ISO 8601 format.

payment_idstring

The Square-issued ID of the payment the refund is applied to.

Settlement

Represents a deposit or withdrawal made by Square to a merchant's bank account.

Fields

NameTypeDescription
idstring

The settlement's unique identifier.

statusSettlement.Status

The settlement's current status.

initiated_atstring

The time when the settlement was submitted for deposit or withdrawal, in ISO 8601 format.

bank_account_idstring

The Square-issued unique identifier for the bank account associated with the settlement.

total_moneyMoney

The amount of money involved in the settlement. A positive amount indicates a deposit, and a negative amount indicates a withdrawal. This amount is never zero.

entriesSettlementEntry[]

The entries included in this settlement.

SettlementEntry

Represents a single entry in a Settlement.

Fields

NameTypeDescription
typeSettlementEntry.Type

The type of activity this entry represents.

payment_idstring

The payment associated with the settlement entry, if any.

amount_moneyMoney

The total amount of money this entry contributes to the total settlement amount.

fee_moneyMoney

The amount of all Square fees associated with this settlement entry. This value is always negative or zero.

This amount has already been applied to amount_money.

Subscription

Represents a merchant's subscription to an application.

Fields

NameTypeDescription
idstring

The subscription's unique ID.

merchant_idstring

The ID of the merchant with the subscription.

plan_idstring

The ID of the SubscriptionPlan the subscription belongs to.

statusSubscription.Status

The subscription's status, such as active or canceled.

payment_methodSubscription.PaymentMethod

The method of payment used to pay the subscription's monthly fee.

fee_base_moneyMoney

The subscription's base monthly fee.

service_start_datestring

The date when the subscription most recently became active, in YYYY-MM-DD format.

feesSubscriptionFee[]

The history of subscription fees paid or pending for this subscription, in reverse chronological order (newest first).

SubscriptionFee

Represents a single fee charged to a merchant for a Subscription.

Fields

NameTypeDescription
fee_datestring

The date when the subscription fee was charged, in YYYY-MM-DD format.

fee_statusSubscriptionFee.Status

The payment status of the subscription fee, such as PENDING or PAID.

fee_base_moneyMoney

The subscription fee's base amount.

fee_tax_moneyMoney

The total of all taxes applied to the subscription fee.

fee_total_moneyMoney

The subscription fee's total amount. This is always the sum of fee_base_money and fee_tax_money.

SubscriptionPlan

Represents an application subscription plan.

Fields

NameTypeDescription
idstring

The plan's unique ID.

namestring

The plan's name.

country_codestring

The country the plan applies to, in ISO 3166-1-alpha-2 format.

fee_base_moneyMoney

The plan's base monthly fee.

Tender

Represents a form and amount of tender provided for a payment. Multiple forms of tender can be provided for a single payment.

Fields

NameTypeDescription
idstring

The tender's unique ID.

typeTender.Type

The type of tender.

namestring

A human-readable description of the tender.

employee_idstring

The ID of the employee that processed the tender.

This field is included only if the associated merchant had employee management features enabled at the time the tender was processed.

receipt_urlstring

The URL of the receipt for the tender.

card_brandTender.CardBrand

The brand of credit card provided.

Only present if the tender's type is CREDIT_CARD.

pan_suffixstring

The last four digits of the provided credit card's account number.

Only present if the tender's type is CREDIT_CARD.

entry_methodTender.EntryMethod

The method with which the tender was entered.

payment_notestring

Notes entered by the merchant about the tender at the time of payment, if any. Typically only present for tender with the typeOTHER.

total_moneyMoney

The total amount of money provided in this form of tender.

tendered_moneyMoney

The amount of total_money applied to the payment.

change_back_moneyMoney

The amount of total_money returned to the buyer as change.

refunded_moneyMoney

The total of all refunds applied to this tender. This amount is always negative or zero.

Timecard

Represents a timecard for an employee.

Fields

NameTypeDescription
idstring

The timecard's unique ID.

employee_idstring

The ID of the employee the timecard is associated with.

deletedboolean

If true, the timecard was deleted by the merchant, and it is no longer valid.

clockin_timestring

The time the employee clocked in, in ISO 8601 format.

clockout_timestring

The time the employee clocked out, in ISO 8601 format.

clockin_location_idstring

The ID of the location the employee clocked in from, if any.

clockout_location_idstring

The ID of the location the employee clocked out from, if any.

created_atstring

The time when the timecard was created, in ISO 8601 format.

updated_atstring

The time when the timecard was most recently updated, in ISO 8601 format.

TimecardEvent

Represents an event associated with a timecard, such as an employee clocking in.

Fields

NameTypeDescription
idstring

The event's unique ID.

event_typeTimecardEvent.Type

The type of action performed on the timecard, such as CLOCKIN or API_CREATE.

clockin_timestring

The time the employee clocked in, in ISO 8601 format.

clockout_timestring

The time the employee clocked out, in ISO 8601 format.

created_atstring

The time when the event was created, in ISO 8601 format.

Connect API Enums

BankAccount.Type

A bank account's type (savings, checking, and so on).

ValueDescription
BUSINESS_CHECKING

A business checking account.

CHECKING

A checking account.

INVESTMENT

An investment account.

LOAN

A loan account.

SAVINGS

A savings account.

OTHER

A type of bank account that does not match any other value.

CashDrawerEvent.Type

The type of event that caused a merchant's cash drawer to open.

ValueDescription
NO_SALE

An employee opened the cash drawer by performing a "No Sale" operation. This also creates a zero-value payment.

CASH_TENDER_PAYMENT

An employee processed a cash payment.

OTHER_TENDER_PAYMENT

An employee processed a payment with the OTHER tender type.

CASH_TENDER_CANCELED_PAYMENT

An employee began to process a cash payment that was subsequently canceled.

OTHER_TENDER_CANCELED_PAYMENT

An employee began to process a payment with the OTHER tender type that was subsequently canceled.

CASH_TENDER_REFUND

An employee processed a refund for a cash payment.

OTHER_TENDER_REFUND

An employee processed a refund for a payment with the OTHER tender type.

PAID_IN

Money was added to the cash drawer for a non-payment reason (such as to restock it).

PAID_OUT

Money was removed from the cash drawer for a non-refund reason (such as to pay a delivery person).

CashDrawerShift.State

Indicates a cash drawer shift's current state.

ValueDescription
OPEN

The shift has been started by an authorized employee, but not yet ended.

ENDED

The shift has been ended by an authorized employee.

CLOSED

The shift has been closed by an authorized employee, meaning they have manually counted and entered the final amount in the cash drawer.

Discount.Type

Indicates whether a discount's value is fixed or entered at the time of sale.

ValueDescription
FIXED

The discount has a fixed value.

VARIABLE_PERCENTAGE

The discount is percentage-based and entered at the time of sale.

VARIABLE_AMOUNT

The discount is amount-based and entered at the time of sale.

Employee.Status

Indicates whether an employee is active or inactive.

ValueDescription
ACTIVE

The employee is active.

INACTIVE

The employee is inactive.

EmployeeRole.Permission

Permissions that can be granted to an employee role. If a role has been granted a particular permission, all employees with that role have that permission.

ValueDescription
REGISTER_ACCESS_SALES_HISTORY

Allows employees to access the merchant's sales history in Square Point of Sale.

REGISTER_APPLY_RESTRICTED_DISCOUNTS

Allows employees to apply restricted discounts to a sale in Square Point of Sale.

REGISTER_CHANGE_SETTINGS

Allows employees to change the merchant's Square Point of Sale settings (such as enabling or disabling tipping).

REGISTER_EDIT_ITEM

Allows employees to edit the merchant's item library in Square Point of Sale. The item library includes all item-related entities, such as discounts and fees.

REGISTER_ISSUE_REFUNDS

Allows employees to issue refunds for payments.

REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE

Allows employees to open the cash drawer in circumstances other than during a cash transaction.

REGISTER_VIEW_SUMMARY_REPORTS

Allows employees to view sales summary reports in Square Point of Sale.

Fee.AdjustmentType

Indicates the type of adjustment a fee applies to a payment. Currently, this value is TAX for all fees.

ValueDescription
TAX

The fee is a tax.

Fee.CalculationPhase

Indicates whether a fee is calculated based on a payment's subtotal or total.

ValueDescription
FEE_SUBTOTAL_PHASE

The fee is calculated based on the payment's subtotal.

FEE_TOTAL_PHASE

The fee is calculated based on the payment's total.

OTHER

A calculation phase that does not match any other value.

Fee.InclusionType

Indicates whether a fee applied to an item is additive or inclusive.

  • Additive fees are added on top of the price of items they're applied to. If an additive 10% fee is applied to a $100 item, the total is $110.
  • Inclusive fees are assumed to already be included in the price of the items they apply to. If an inclusive 10% fee is applied to a $100 item, the total is $100, and the actual base cost of the item is assumed to be $90.91. This affects the amount of any additive fees that are also applied to the item.
ValueDescription
ADDITIVE

The fee is an additive fee.

INCLUSIVE

The fee is an inclusive fee.

Fee.Type

Indicates which sales tax classification the fee falls under. Currently relevant only to Canadian merchants.

ValueDescription
CA_GST

The fee is a Goods and Services Tax (GST).

CA_HST

The fee is a Harmonized Sales Tax (HST).

CA_PEI_PST

The fee is a Prince Edward Island provincial sales tax.

CA_PST

The fee is a provincial sales tax (PST).

CA_QST

The fee is a Quebec Sales Tax (QST).

JP_CONSUMPTION_TAX

The fee is a Japanese consumption tax. All fees created by Japanese merchants have this type.

US_SALES_TAX

The fee is a US sales tax. All fees created by US merchants have this type.

OTHER

The fee is a type that does not match any other value.

InventoryAdjustmentType

Indicates the reason for adjusting an item variation's inventory information.

ValueDescription
SALE

The available quantity is being reduced due to a sale.

RECEIVE_STOCK

The available quanitity is being increased due to an increase in stock.

MANUAL_ADJUST

The available quantity is being adjusted manually due to an updated stock count or other discrepancy.

InventoryAlertType

Indicates whether the item variation generates an alert when its inventory quantity goes below its inventory_alert_threshold.

ValueDescription
LOW_QUANTITY

The variation generates an alert when its quantity is low.

NONE

The variation does not display an alert.

Item.Color

Indicates the color of an item's label color in Square Point of Sale, in six-character hexadecimal format. Colors other than those listed are not supported.

ValueDescription
9da2a6

A gray color.

4ab200

A lighter green color.

0b8000

A darker green color.

13b1bf

A lighter blue color.

2952cc

A darker blue color.

a82ee5

A purple color.

e5457a

A lighter red color.

b21212

A dark red color.

e5BF00

A gold color.

593c00

A brown color.

Item.Type

Indicates an item's type. Almost all items have the type NORMAL.

You cannot set an item's type with the Connect API.

ValueDescription
NORMAL

The item is a normal item in the merchant's item library.

GIFT_CARD

The item is a Square gift card sold by the merchant.

OTHER

The item has a type that doesn't match any other value.

Item.Visibility

Indicates whether an item is viewable from a merchant's online store. This does not indicate whether the item is available for purchase in the online store.

ValueDescription
PUBLIC

The item is viewable from the online store.

PRIVATE

The item is not viewable from the online store.

ItemVariation.PricingType

Indicates whether an item variation's price is fixed or entered at the time of sale.

ValueDescription
FIXED_PRICING

The item variation's price is fixed.

VARIABLE_PRICING

The item variation's price is entered at the time of sale.

ListOrder

The chronological order in which results from a request are returned.

ValueDescription
ASC

Results are returned in standard chronological order (oldest first).

DESC

Results are returned in reverse-chronological order (newest first).

Money.CurrencyCode

Indicates the currency associated with an amount of money.

ValueDescription
CAD

Canadian dollars.

JPY

Japanese yen.

USD

US dollars.

AED

ALL

AMD

AOA

ARS

AUD

AWG

AZN

BAM

BBD

BDT

BGN

BHD

BMD

BND

BOB

BRL

BSD

BTN

BWP

BYR

BZD

CDF

CHF

CLP

CNY

COP

CRC

CVE

CZK

DKK

DOP

DZD

EGP

ETB

EUR

FJD

GBP

GEL

GHS

GIP

GMD

GTQ

GYD

HKD

HNL

HRK

HTG

HUF

IDR

ILS

INR

ISK

JMD

JOD

KES

KGS

KHR

KRW

KWD

KYD

KZT

LAK

LBP

LKR

LRD

LTL

MAD

MDL

MGA

MKD

MMK

MNT

MOP

MRO

MUR

MWK

MXN

MYR

MZN

NAD

NGN

NIO

NOK

NPR

NZD

OMR

PAB

PEN

PGK

PHP

PKR

PLN

PYG

QAR

RON

RSD

RUB

RWF

SAR

SBD

SCR

SEK

SGD

SLL

SRD

STD

SVC

SZL

THB

TJS

TMT

TND

TRY

TTD

TWD

TZS

UAH

UGX

UYU

UZS

VEF

VND

XAF

XCD

XOF

YER

ZAR

ZMW

Merchant.BusinessType

Indicates a merchant's type of business.

Business type values are applicable to all countries supported by Square unless otherwise indicated.

ValueDescription
ACCOUNTING

APPAREL_AND_ACCESSORY_SHOPS

ART_DEALERS_GALLERIES

ART_DESIGN_AND_PHOTOGRAPHY

BAR_CLUB_LOUNGE

Not applicable to Japanese businesses.

BEAUTY_AND_BARBER_SHOPS

BOOK_STORES

Applicable to Japanese businesses only.

BUSINESS_SERVICES

Not applicable to Japanese businesses.

CATERING

CHARITABLE_SOCIAL_SERVICE_ORGANIZATIONS

Not applicable to Japanese businesses.

CHARITIBLE_ORGS

CLEANING_SERVICES

Not applicable to Japanese businesses.

COMPUTER_EQUIPMENT_SOFTWARE_MAINTENANCE_REPAIR_SERVICES

CONSULTANT

CONTRACTORS

DELIVERY_SERVICES

Applicable to Japanese businesses only.

DENTISTRY

EDUCATION

FOOD_STORES_CONVENIENCE_STORES_AND_SPECIALTY_MARKETS

FOOD_TRUCK_CART

FURNITURE_HOME_AND_OFFICE_EQUIPMENT

Applicable to Japanese businesses only.

FURNITURE_HOME_GOODS

Not applicable to Japanese businesses.

HOTELS_AND_LODGING

Applicable to Japanese businesses only.

INDIVIDUAL_USE

Not applicable to Japanese businesses.

JEWELRY_AND_WATCHES

Not applicable to Japanese businesses.

LANDSCAPING_AND_HORTICULTURAL_SERVICES

LANGUAGE_SCHOOLS

Applicable to Japanese businesses only.

LEGAL_SERVICES

MEDICAL_PRACTITIONERS

Not applicable to Japanese businesses.

MEDICAL_SERVICES_AND_HEALTH_PRACTITIONERS

MEMBERSHIP_ORGANIZATIONS

MUSIC_AND_ENTERTAINMENT

OTHER

Applicable to Japanese businesses only.

OUTDOOR_MARKETS

PERSONAL_SERVICES

POLITICAL_ORGANIZATIONS

Applicable to US businesses only.

PROFESSIONAL_SERVICES

REAL_ESTATE

RECREATION_SERVICES

REPAIR_SHOPS_AND_RELATED_SERVICES

RESTAURANTS

RETAIL_SHOPS

SCHOOLS_AND_EDUCATIONAL_SERVICES

Not applicable to Japanese businesses.

SPORTING_GOODS

Not applicable to Japanese businesses.

TAXICABS_AND_LIMOUSINES

TICKET_SALES

Applicable to Japanese businesses only.

TOURISM

Not applicable to Japanese businesses.

TRAVEL_TOURISM

Applicable to Japanese businesses only.

VETERINARY_SERVICES

WEB_DEV_DESIGN

Merchant.AccountType

Indicates whether a merchant account is a single-location account or a business account.

ValueDescription
BUSINESS

The account is a business account.

LOCATION

The account is a single-location account.

Merchant.AccountCapability

Capabilities that a merchant's associated Square account might have. You can get a merchant's account capabilities with the Retrieve Mechant endpoint.

ValueDescription
CREDIT_CARD_PROCESSING

The merchant can process credit cards with Square.

ModifierList.SelectionType

Indicates whether more than one modifier option from a single modifier list can be applied to a single item.

ValueDescription
SINGLE

Only one option from the modifier list can be applied to a given item.

MULTIPLE

Multiple options from the modifier list can be applied to a given item.

OAuth.Permission

Represents the possible permissions an application can request with the Permissions form. See Permission scope for values.

ValueDescription

Order.Action

An action a merchant performs on an online store order to change its state.

ValueDescription
COMPLETE

The merchant shipped or otherwise fulfilled the order. Sets the order's state to COMPLETED.

CANCEL

The merchant canceled the order. Sets the order's state to CANCELED.

REFUND

The merchant refunded the previously COMPLETED order. Sets the order's state to REFUNDED.

Order.State

The current state of an online storer order.

ValueDescription
PENDING

The order has been created and is awaiting validation from Square.

OPEN

The order has been validated and is ready to be completed by the merchant.

COMPLETED

The merchant shipped or otherwise fulfilled the order.

CANCELED

The merchant canceled the order or didn't act on it within a required time period.

REFUNDED

The merchant refunded a previously COMPLETED order.

REJECTED

The order cannot be processed because it was rejected by Square, or because it has been too long since the order was created

OrderHistoryEntry.ActionType

The type of action previously performed on an online store order.

ValueDescription
ORDER_PLACED

The buyer initiated the order.

DECLINED

The order was rejected by Square.

PAYMENT_RECEIVED

The order's associated payment was processed.

CANCELED

The merchant canceled the order.

COMPLETED

The merchant shipped or otherwise fulfilled the order.

REFUNDED

The merchant refunded the order.

EXPIRED

The order expired.

PaymentItemization.Type

The type of purchase that a payment itemization represents.

ValueDescription
ITEM

The itemization represents an item variation from the merchant's item library.

CUSTOM_AMOUNT

The itemization represents a monetary amount that is not associated with an item variation.

GIFT_CARD_ACTIVATION

The itemization represents the activation of a Square gift card.

GIFT_CARD_RELOAD

The itemization represents adding funds to a Square gift card.

GIFT_CARD_UNKNOWN

The itemization represents an unknown action performed on a Square gift card.

OTHER

The itemization represents an entity that doesn't match any other value.

Refund.Type

A refund's type.

ValueDescription
FULL

A full refund.

PARTIAL

A partial refund.

PageCell.Type

The type of entity represented by a page cell.

ValueDescription
ITEM

An item.

DISCOUNT

A discount.

CATEGORY

A category.

PLACEHOLDER

The cell is one of the special types described in PageCell.PlaceholderType.

PageCell.PlaceholderType

Indicates the behavior of a page cell with the special PLACEHOLDER object type. See Favorites Pages for more information.

ValueDescription
ALL_ITEMS

The cell presents a list of all the merchant's items. The cell is labeled All Items.

DISCOUNTS_CATEGORY

The cell presents a list of all the merchant's discounts. The cell is labeled Discounts.

REWARDS_FINDER

The cell presents a view for selecting customer rewards. The cell is labeled Redeem Rewards.

Learn more about Square Point of Sale rewards.

RequestMethod

The method type of an HTTP request.

ValueDescription
DELETE

A DELETE request.

GET

A GET request.

POST

A POST request.

PUT

A PUT request.

SettlementEntry.Type

The type of a single entry within a settlement. The most common types are CHARGE and REFUND. All other types are uncommon or extremely rare, with some no longer appearing in new settlements.

Types that begin with RETURNED represent reattempting a previously failed action.

ValueDescription
ADJUSTMENT

A manual adjustment applied to the merchant's account by Square. Adjustments typically correct minor calculation errors.

BALANCE_CHARGE

Crediting the merchant for a previously processed payment where the buyer paid with an existing Square balance, such as a Square gift card.

CHARGE

Crediting the merchant for a previously processed credit card payment. Most settlement entries have this type.

FREE_PROCESSING

Crediting the merchant to offset processing fees, because the merchant has been granted an amount of free processing.

HOLD_ADJUSTMENT

An adjustment related to the holding of funds from a previous payment, often related to a chargeback or a similar dispute.

The amount of a HOLD_ADJUSTMENT settlement entry can be negative or positive, depending on whether a hold is being applied (negative) or a previously applied hold is being released (positive).

PAID_SERVICE_FEE

Debiting the merchant for a paid service, such as Square Marketing.

PAID_SERVICE_FEE_REFUND

Refunding the merchant for a previously paid service fee.

REDEMPTION_CODE

Crediting the merchant for a code redeemed from a Square Reader purchased from a retail location.

REFUND

Debiting the merchant for a refund applied to a previously processed payment.

RETURNED_PAYOUT

Reattempting a previously failed deposit.

SQUARE_CAPITAL_ADVANCE

A Square Capital advance paid to the merchant.

SQUARE_CAPITAL_PAYMENT

Debiting the merchant for payment toward a SQUARE_CAPITAL_ADVANCE.

SQUARE_CAPITAL_REVERSED_PAYMENT

Reversing a portion of a previous SQUARE_CAPITAL_PAYMENT, typically in response to a merchant-issued refund.

SUBSCRIPTION_FEE

Debiting the merchant for a subscription fee payment.

SUBSCRIPTION_FEE_REFUND

Refunding the merchant for a previously paid subscription fee.

OTHER

A type of settlement entry that does not match any other value.

INCENTED_PAYMENT

Deprecated. Crediting the merchant for a payment in which Square covers part of the amount due.

This value does not appear in new settlements.

RETURNED_ACH_ENTRY

Deprecated. Reattempting a previously failed deposit.

This value does not appear in new settlements.

RETURNED_SQUARE_275

Deprecated. Reattempting a previously failed Square 275 payment. Square 275 is a discontinued subscription pricing model for larger Square merchants.

This value does not appear in new settlements.

SQUARE_275

Deprecated. Debiting the merchant for a Square 275 payment. Square 275 is a discontinued subscription pricing model for larger Square merchants.

This value does not appear in new settlements.

Settlement.Status

The current status of a settlement. Note that Square does not know when a settlement that's been SENT for processing completes, only whether it's FAILED.

ValueDescription
FAILED

The settlement failed.

SENT

The settlement was sent for processing.

Subscription.PaymentMethod

The form of payment used for a merchant's subscription.

ValueDescription
CARD

A credit card on file.

PAYOUT_ADJUSTMENT

Payment is withdrawn from the merchant's bank account as part of the standard merchant settlement process.

OTHER

The merchant used a payment method that does not match any other value.

Subscription.Status

The status of a merchant's subscription.

ValueDescription
ACTIVE

The merchant has an active, fully paid subscription.

IN_GRACE

The merchant's automatic monthly subscription payment failed (possibly due to an invalid payment method). The merchant is in a fifteen-day grace period, during which their subscription is considered active.

DELINQUENT

The merchant's subscription has become inactive because the merchant did not successfully pay the subscription fee by the end of the fifteen-day grace period.

This value is no longer returned by the Connect API. Delinquent subscriptions are now returned as CANCELED.

CANCELED

The merchant's subscription was canceled.

TERMINATED

The merchant's subscription was terminated.

OTHER

The subscription has a status that does not match any other value.

SubscriptionFee.Status

The status of a merchant's application subscription fee, such as PENDING or PAID.

ValueDescription
PENDING

The fee payment is pending.

PAYMENT_FAILED

The fee payment failed, usually because of a declined or otherwise invalid credit card.

PAID

The fee payment succeeded.

CANCELED

The fee payment was canceled, usually because the merchant canceled their subscription or changed their subscription plan.

OTHER

The fee payment has a status that does not match any other value.

Tender.CardBrand

The brand of a credit card.

ValueDescription
UNKNOWN

An unknown brand.

VISA

A Visa credit card.

MASTER_CARD

A MasterCard credit card.

AMERICAN_EXPRESS

An American Express credit card.

DISCOVER

A Discover credit card.

DISCOVER_DINERS

A Diners Club credit card.

JCB

A JCB credit card.

Tender.EntryMethod

The method with which a form of tender was entered.

ValueDescription
MANUAL

The payment information was entered manually.

SCANNED

The payment information was scanned via barcode.

SQUARE_CASH

The payment was made via Square Cash.

SQUARE_WALLET

The payment was made via Square Wallet.

SWIPED

The payment card was swiped through a card reader.

WEB_FORM

The payment was made via a web form.

OTHER

The payment information was obtained by a method that does not match any other value.

Tender.Type

The type of tender used in a payment.

ValueDescription
CREDIT_CARD

A credit card processed with Square.

CASH

Cash.

THIRD_PARTY_CARD

A credit card processed with a card processor other than Square.

This value applies only to merchants in countries where Square does not yet provide card processing.

NO_SALE

No sale.

SQUARE_WALLET

A Square Wallet payment.

SQUARE_GIFT_CARD

A Square gift card.

UNKNOWN

An unknown tender type.

OTHER

A form of tender that does not match any other value.

TimecardEvent.Type

The type of event associated with an employee timecard, such as CLOCKIN.

ValueDescription
API_CREATE

The timecard was created by a request to the Create Timecard endpoint.

API_EDIT

The timecard was edited by a request to the Update Timecard endpoint.

API_DELETE

The timecard was deleted by a request to the Delete Timecard endpoint.

REGISTER_CLOCKIN

The employee clocked in.

REGISTER_CLOCKOUT

The employee clocked out.

DASHBOARD_SUPERVISOR_CLOSE

A supervisor clocked out the employee from the merchant dashboard.

DASHBOARD_EDIT

A supervisor manually edited the timecard from the merchant dashboard.

DASHBOARD_DELETE

A supervisor deleted the timecard from the merchant dashboard.

WebhookEventType

The type of an event that sends a notification to an application.

ValueDescription
PAYMENT_UPDATED

A payment was updated or created.

INVENTORY_UPDATED

At least one item variation's inventory count was updated.

TIMECARD_UPDATED

An employee timecard was updated or created.