Connect v1 API Reference

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:

Type Description
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 via Square Point of Sale.
REGISTER_CLOCKOUT The employee clocked out via Square Point of Sale.
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.

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.

Name Type Description
first_name string

The employee's first name.

last_name string

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.

Name Type Description
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

Name Type Description
employee_id string

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

Name Type Description
employee_id string

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.

Name Type Description
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.

Name Type Description
name string

The role's name.

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

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.

Name Type Description
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

Name Type Description
role_id string

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

Name Type Description
role_id string

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.

Name Type Description
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.

Name Type Description
employee_id string

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. We strongly reccomend providing a clockin_location_id. Square uses the clockin_location_id to determine a timecard’s timezone and overtime rules.

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.

Name Type Description
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

Name Type Description
timecard_id string

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

Name Type Description
timecard_id string

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.

Name Type Description
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. We strongly reccomend providing a clockin_location_id. Square uses the clockin_location_id to determine a timecard’s timezone and overtime rules.

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

Name Type Description
timecard_id string

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

Name Type Description
timecard_id string

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

Name Type Description
location_id string

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.

Name Type Description
begin_time (optional) string

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

Default value: The current time minus 90 days.

end_time (optional) string

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

Name Type Description
location_id string

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

shift_id string

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:

Field Description
inclusive_tax_money The total of all inclusive taxes applied to the payment.
additive_tax_money The total of all additive taxes applied to the payment.
tax_money The sum of inclusive_tax_money and additive_tax_money.
tip_money The total of all tips applied to the payment.
discount_money The total of all discounts applied to the payment.
total_collected_money The grand total for the payment (the amount that the buyer actually paid).
processing_fee_money The amount of all Square processing fees applied to the payment.
net_total_money The amount that was (or will be) deposited into the merchant's bank account.
refunded_money The 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.

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

Name Type Description
location_id string

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.

Name Type Description
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

include_partial (optional) boolean

Indicates whether or not to include partial payments in the response. Partial payments will have the tenders collected so far, but the itemizations will be empty until the payment is completed.

Default value: false

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

Name Type Description
location_id string

The ID of the payment's associated location.

Get a business' locations with the List Locations endpoint.

payment_id string

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

Name Type Description
location_id string

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.

Name Type Description
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"
    }
  },
  {
    "id": "C:83SALJHODOC94",
    "status": "SENT",
    "bank_account_id": "JGHJ0343",
    "initiated_at": "2014-01-02T09:00:00.000Z",
    "total_money": {
      "amount": 1738,
      "currency_code": "USD"
    }
  },
  {
    "id": "D:45AFMNAONNA40",
    "status": "SENT",
    "bank_account_id": "JGHJ0343",
    "initiated_at": "2014-11-02T09:00:00.000Z",
    "total_money": {
      "amount": 1984,
      "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

Name Type Description
location_id string

The ID of the settlement's associated location.

Get a business' locations with the List Locations endpoint.

settlement_id string

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.

NOTE: Card-present transactions with Interac credit cards cannot be refunded using the Connect API. Interac transactions must refunded in-person (e.g., dipping the card using POS app).

Required permissions: PAYMENTS_WRITE

Path Parameters

Name Type Description
location_id string

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.

Name Type Description
payment_id string

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.

type Refund.Type

The type of refund (FULL or PARTIAL).

reason string

The reason for the refund.

refunded_money Money

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

Name Type Description
location_id string

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.

Name Type Description
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 approximate number of refunds to return in a single response. The value cannot exceed 200.

This value is always an integer.

The response may contain more results than the limit when refunds are made simultaneously to multiple tenders in a payment, or when refunds are generated to account for the value of returned goods in an exchange.

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

Name Type Description
location_id string

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

Name Type Description
location_id string

The ID of the bank account's associated location.

Get a business' locations with the List Locations endpoint.

bank_account_id string

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

Name Type Description
location_id string

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.

Name Type Description
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.

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

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

variations ItemVariation[]

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

Name Type Description
location_id string

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

Name Type Description
location_id string

The ID of the item's associated location.

Get a business' locations with the List Locations endpoint.

item_id string

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

Name Type Description
location_id string

The ID of the item's associated location.

Get a business' locations with the List Locations endpoint.

item_id string

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.

Name Type Description
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

Name Type Description
location_id string

The ID of the item's associated location.

Get a business' locations with the List Locations endpoint.

item_id string

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

Name Type Description
location_id string

The ID of the item's associated location.

Get a business' locations with the List Locations endpoint.

item_id string

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.

Name Type Description
image_data data

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

Name Type Description
merchant_id string

The ID of the item's associated location.

Get a business' locations with the List Locations endpoint.

item_id string

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.

Name Type Description
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.

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

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_data (optional) string

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

Name Type Description
location_id string

The ID of the variation's associated location.

Get a business' locations with the List Locations endpoint.

item_id string

The ID of the item the variation applies to.

variation_id string

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.

Name Type Description
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_data string

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

Name Type Description
location_id string

The ID of the variation's associated location.

Get a business' locations with the List Locations endpoint.

item_id string

The ID of the item the variation applies to.

variation_id string

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

Name Type Description
location_id string

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.

Name Type Description
limit number

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

Name Type Description
location_id string

The ID of the variation's associated location.

Get a business' locations with the List Locations endpoint.

variation_id string

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.

Name Type Description
quantity_delta number

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_type InventoryAdjustmentType

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

Name Type Description
location_id string

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.

Name Type Description
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.

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

Default value: SINGLE

modifier_options ModifierOption[]

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

Name Type Description
location_id string

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

Name Type Description
location_id string

The ID of the modifier list's associated location.

Get a business' locations with the List Locations endpoint.

modifier_list_id string

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

Name Type Description
location_id string

The ID of the modifier list's associated location.

Get a business' locations with the List Locations endpoint.

modifier_list_id string

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.

Name Type Description
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

Name Type Description
location_id string

The ID of the modifier list's associated location.

Get a business' locations with the List Locations endpoint.

modifier_list_id string

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

Name Type Description
location_id string

The ID of the modifier list's associated location.

Get a business' locations with the List Locations endpoint.

item_id string

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

modifier_list_id string

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

Name Type Description
location_id string

The ID of the modifier list's associated location.

Get a business' locations with the List Locations endpoint.

item_id string

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

modifier_list_id string

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

Name Type Description
location_id string

The ID of the modifier list's associated location.

Get a business' locations with the List Locations endpoint.

modifier_list_id string

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.

Name Type Description
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.

name string

The modifier option's name.

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

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

Name Type Description
location_id string

The ID of the modifier option's associated location.

Get a business' locations with the List Locations endpoint.

modifier_list_id string

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

modifier_option_id string

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.

Name Type Description
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

Name Type Description
location_id string

The ID of the modifier option's associated location.

Get a business' locations with the List Locations endpoint.

modifier_list_id string

The ID of the modifier list that contains the option.

modifier_option_id string

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

Name Type Description
location_id string

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.

Name Type Description
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.

name string

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

Name Type Description
location_id string

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

Name Type Description
location_id string

The ID of the category's associated location.

Get a business' locations with the List Locations endpoint.

category_id string

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.

Name Type Description
name string

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

Name Type Description
location_id string

The ID of the category's associated location.

category_id string

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

Name Type Description
location_id string

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.

Name Type Description
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.

name 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 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

Name Type Description
location_id string

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

Name Type Description
location_id string

The ID of the discount's associated location.

Get a business' locations with the List Locations endpoint.

discount_id string

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.

Name Type Description
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

Name Type Description
location_id string

The ID of the discount's associated location.

Get a business' locations with the List Locations endpoint.

discount_id string

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

Name Type Description
location_id string

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.

Name Type Description
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.

name string

The fee's name.

rate 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 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

Name Type Description
location_id string

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

Name Type Description
location_id string

The ID of the fee's associated location.

Get a business' locations with the List Locations endpoint.

fee_id string

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.

Name Type Description
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

Name Type Description
location_id string

The ID of the fee's associated location.

Get a business' locations with the List Locations endpoint.

fee_id string

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

Name Type Description
location_id string

The ID of the fee's associated location.

Get a business' locations with the List Locations endpoint.

item_id string

The ID of the item to add the fee to.

fee_id string

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

Name Type Description
location_id string

The ID of the fee's associated location.

Get a business' locations with the List Locations endpoint.

item_id string

The ID of the item to remove the fee from.

fee_id string

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 6, 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

Name Type Description
location_id string

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.

Name Type Description
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_index number

The page's position in the list of pages. Must be an integer between 0 and 6, 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

Name Type Description
location_id string

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

Name Type Description
location_id string

The ID of the Favorites page's associated location.

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

page_id string

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.

Name Type Description
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 6, 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

Name Type Description
location_id string

The ID of the Favorites page's associated location.

Get a business' locations with the List Locations endpoint.

page_id string

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

Name Type Description
location_id string

The ID of the Favorites page's associated location.

Get a business' locations with the List Locations endpoint.

page_id string

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.

Name Type Description
row number

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

column number

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

object_type PageCell.Type

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

object_id string

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

placeholder_type PageCell.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

Name Type Description
location_id string

The ID of the Favorites page's associated location.

Get a business' locations with the List Locations endpoint.

page_id string

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.

Name Type Description
row number

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

column number

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.

Name Type Description
requests BatchRequest[]

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

Webhook permissions

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

Event type Permission
PAYMENT_UPDATED PAYMENTS_READ
INVENTORY_UPDATED ITEMS_READ
TIMECARD_UPDATED TIMECARDS_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.

List Webhooks

GET /v1/{location_id}/webhooks

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

Path Parameters

Name Type Description
location_id string

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

Name Type Description
location_id string

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"]

Connect API Data Types

BankAccount

Represents a merchant's bank account.

Fields

Name Type Description
id string

The bank account's Square-issued ID.

merchant_id string

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

bank_name string

The name of the bank that manages the account.

name string

The name associated with the bank account.

type BankAccount.Type

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

routing_number string

The bank account's routing number.

account_number_suffix string

The last few digits of the bank account number.

currency_code string

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

Name Type Description
method RequestMethod

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

relative_path string

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_token string

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

body object

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

request_id string

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

Name Type Description
status_code number

The response's HTTP status code.

headers object

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"].

body object

The body of the response, if any.

request_id string

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

Coordinates

Represents geographic coordinates.

Fields

Name Type Description
latitude number

The latitude coordinate, in degrees.

longitude number

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

Name Type Description
id string

The event's unique ID.

employee_id string

The ID of the employee that created the event.

event_type CashDrawerEvent.Type

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

event_money Money

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_at string

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

description string

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

Name Type Description
id string

The shift's unique ID.

cash_drawer_state CashDrawerShift.State

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

opened_at string

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

ended_at string

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

closed_at string

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

employee_ids string[]

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

opening_employee_id string

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

ending_employee_id string

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

closing_employee_id string

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

description string

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

starting_cash_money Money

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

cash_payment_money Money

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

cash_refunds_money Money

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

cash_paid_in_money Money

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

cash_paid_out_money Money

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

expected_cash_money Money

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_money Money

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

device Device

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

events CashDrawerEvent[]

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

Category

Represents an item category.

Fields

Name Type Description
id string

The category's unique ID.

name string

The category's name.

Device

Represents a device running Square Point of Sale.

Fields

Name Type Description
name string

The device's merchant-specified name.

id string

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

Name Type Description
id string

The discount's unique ID.

name string

The discount's name.

rate 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%. This rate is 0 if discount_type is VARIABLE_PERCENTAGE.

This field is not included for amount-based discounts.

amount_money Money

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_type Discount.Type

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

pin_required boolean

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

color Item.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

Name Type Description
id string

The employee's unique ID.

first_name string

The employee's first name.

last_name string

The employee's last name.

role_ids string[]

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

authorized_location_ids string[]

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

email string

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.

status Employee.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_id string

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_at string

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

updated_at string

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

Name Type Description
id string

The role's unique ID.

name string

The role's merchant-defined name.

permissions EmployeeRole.Permission[]

The permissions that the role has been granted.

is_owner boolean

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

created_at string

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

updated_at string

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

Name Type Description
id string

The fee's unique ID.

name string

The fee's name.

rate 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 Fee.CalculationPhase

Forthcoming.

adjustment_type Fee.AdjustmentType

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

applies_to_custom_amounts boolean

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

enabled boolean

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

inclusion_type Fee.InclusionType

Whether the fee is ADDITIVE or INCLUSIVE.

type Fee.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

Name Type Description
address_line_1 string

The first line of the address.

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

address_line_2 string

The second line of the address, if any.

address_line_3 string

The third line of the address, if any.

address_line_4 string

The fourth line of the address, if any.

address_line_5 string

The fifth line of the address, if any.

locality string

The city or town of the address.

sublocality string

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

sublocality_1 string

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

sublocality_2 string

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

sublocality_3 string

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

sublocality_4 string

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

sublocality_5 string

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

administrative_district_level_1 string

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

administrative_district_level_2 string

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

administrative_district_level_3 string

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

postal_code string

The address's postal code.

country_code string

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

address_coordinates Coordinates

The coordinates of the address.

InventoryEntry

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

Fields

Name Type Description
variation_id string

The variation that the entry corresponds to.

quantity_on_hand number

The current available quantity of the item variation.

Item

Represents a merchant's item.

Fields

Name Type Description
id string

The item's unique ID.

name string

The item's name.

description string

The item's description, if any.

type Item.Type

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

abbreviation string

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.

color Item.Color

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

The default color is 9da2a6.

visibility Item.Visibility

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

available_online boolean

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

master_image ItemImage

The item's master image, if any.

category Category

The category the item belongs to, if any.

variations ItemVariation []

The item's variations.

modifier_lists ModifierList []

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

fees Fee []

The fees that apply to the item, if any.

taxable boolean

Deprecated. This field is not used.

ItemImage

Represents an image of an item.

Fields

Name Type Description
id string

The image's unique ID.

url string

The image's publicly accessible URL.

ItemVariation

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

Fields

Name Type Description
id string

The item variation's unique ID.

name string

The item variation's name.

item_id string

The ID of the variation's associated item.

ordinal number

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_type ItemVariation.PricingType

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

price_money Money

The item variation's price, if any.

sku string

The item variation's SKU, if any.

track_inventory boolean

If true, inventory tracking is active for the variation.

inventory_alert_type InventoryAlertType

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

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

user_data string

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

Merchant

Represents a Square merchant account.

Fields

Name Type Description
id string

The merchant account's unique identifier.

name string

The name associated with the merchant account.

email string

The email address associated with the merchant account.

account_type Merchant.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_capabilities Merchant.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.

Single-location accounts can have: CREDIT_CARD_PROCESSING.

Multi-location accounts can have: CREDIT_CARD_PROCESSING, EMPLOYEE_MANAGEMENT, TIMECARD_MANAGEMENT.

country_code string

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

language_code string

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

currency_code string

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

business_name string

The name of the merchant's business.

business_address GlobalAddress

The address of the merchant's business.

business_phone PhoneNumber

The phone number of the merchant's business.

business_type Merchant.BusinessType

The type of business operated by the merchant.

shipping_address GlobalAddress

The merchant's shipping address.

location_details MerchantLocationDetails

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_url string

The URL of the merchant's online store.

MerchantLocationDetails

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

Fields

Name Type Description
nickname string

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

Name Type Description
id string

The modifier list's unique ID.

name string

The modifier list's name.

selection_type ModifierList.SelectionType

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

modifier_options ModifierOption []

The options included in the modifier list.

ModifierOption

Represents an item modifier option.

Fields

Name Type Description
id string

The modifier option's unique ID.

name string

The modifier option's name.

price_money Money

The modifier option's price.

on_by_default boolean

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

ordinal number

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_id string

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

Name Type Description
amount number

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_code Money.CurrencyCode

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

Page

Represents a Favorites page in the iPad version of Square Point of Sale.

Fields

Name Type Description
id string

The page's unique identifier.

name string

The page's name, if any.

page_index number

The page's position in the merchant's list of pages. Always an integer between 0 and 6, inclusive.

cells PageCell []

The cells included on the page.

PageCell

Represents a cell of a Page .

Fields

Name Type Description
page_id string

The unique identifier of the page the cell is included on.

row number

The row of the cell. Always an integer between 0 and 4, inclusive.

column number

The column of the cell. Always an integer between 0 and 4, inclusive.

object_type PageCell.Type

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

object_id string

The unique identifier of the entity represented in the cell. Not present for cells with an object_type of PLACEHOLDER.

placeholder_type PageCell.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

Name Type Description
id string

The payment's unique identifier.

merchant_id string

The unique identifier of the merchant that took the payment.

created_at string

The time when the payment was created, in ISO 8601 format. Reflects the time of the first payment if the object represents an incomplete partial payment, and the time of the last or complete payment otherwise.

creator_id string

The unique identifier of the Square account that took the payment.

This value can differ from merchant_id if the merchant has mobile staff.

device Device

The device that took the payment.

payment_url string

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_url string

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_money Money

The sum of all inclusive taxes associated with the payment.

additive_tax_money Money

The sum of all additive taxes associated with the payment.

tax_money Money

The total of all taxes applied to the payment.

This is always the sum of inclusive_tax_money and additive_tax_money.

tip_money Money

The total of all tips applied to the payment.

discount_money Money

The total of all discounts applied to the payment.

This value is always 0 or negative.

total_collected_money Money

The total amount of money collected from the buyer for the payment.

processing_fee_money Money

The total of all processing fees collected by Square for the payment.

This value is always 0 or negative.

net_total_money Money

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_money Money

The total of all refunds applied to the payment.

swedish_rounding_money Money

The total of all sales, including any applicable taxes, rounded to the smallest legal unit of currency (e.g., the nearest penny in USD, the nearest nickel in CAD)

gross_sales_money Money

The total cost of the itemization and its modifiers, not including taxes or discounts.

net_sales_money Money

The sum of gross_sales_money and discount_money.

inclusive_tax PaymentTax []

All of the inclusive taxes associated with the payment.

additive_tax PaymentTax []

All of the additive taxes associated with the payment.

tender Tender []

The form(s) of tender provided by the buyer for the payment.

refunds Refund []

All of the refunds applied to the payment.

Note that the value of all refunds on a payment can exceed the value of all tenders, because a merchant can choose to refund money to a tender after already accepting some good for exchange.

itemizations PaymentItemization []

The items purchased in the payment.

surcharge_money Money

The total of all surcharges applied to the payment.

surcharges PaymentSurcharge []

A list of all surcharges associated with the payment.

is_partial boolean

Indicates whether or not the payment is only partially paid for. If true, this payment will have the tenders collected so far, but the itemizations will be empty until the payment is completed.

PaymentDiscount

Represents a discount applied to an itemization in a payment.

Fields

Name Type Description
name string

The discount's name.

applied_money Money

The amount of money that this discount adds to the payment (note that this value is always negative or zero).

discount_id string

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

Name Type Description
category_name string

The name of the item's merchant-defined category, if any.

sku string

The item's merchant-defined SKU, if any.

item_id string

The unique ID of the item purchased, if any.

item_variation_id string

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

Name Type Description
name string

The item's name.

quantity number

The quantity of the item purchased. This can be a decimal value.

itemization_type PaymentItemization.Type

The type of purchase that the itemization represents, such as an ITEM or CUSTOM_AMOUNT.

item_detail PaymentItemDetail

Details of the item, including its unique identifier and the identifier of the item variation purchased.

notes string

Notes entered by the merchant about the item at the time of payment, if any.

item_variation_name string

The name of the item variation purchased, if any.

total_money Money

The total cost of the item, including all taxes and discounts.

single_quantity_money Money

The cost of a single unit of this item.

gross_sales_money Money

The total cost of the itemization and its modifiers, not including taxes or discounts.

discount_money Money

The total of all discounts applied to the itemization. This value is always negative or zero.

net_sales_money Money

The sum of gross_sales_money and discount_money.

taxes PaymentTax []

All taxes applied to this itemization.

discounts PaymentDiscount []

All discounts applied to this itemization.

modifiers PaymentModifier []

All modifier options applied to this itemization.

PaymentModifier

Represents a modifier option applied to an itemization in a payment.

Fields

Name Type Description
name string

The modifier option's name.

applied_money Money

The amount of money that this modifier option adds to the payment.

modifier_option_id string

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

Name Type Description
name string

The merchant-defined name of the tax.

applied_money Money

The amount of money that this tax adds to the payment.

rate string

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_type Fee.InclusionType

Whether the tax is an ADDITIVE tax or an INCLUSIVE tax.

fee_id string

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

Name Type Description
calling_code string

The phone number's international calling code. For US phone numbers, this value is +1.

number string

The phone number.

PaymentSurcharge

Represents a surcharge applied to a payment.

Fields

Name Type Description
name string

The name of the surcharge.

applied_money Money

"The amount of money applied to the order as a result of the surcharge."

rate string

The amount of the surcharge as a percentage. The percentage is provided as a string representing the decimal equivalent of the percentage. For example, "0.7" corresponds to a 7% surcharge. Exactly one of rate or amount_money should be set.

amount_money Money

"The amount of the surcharge as a Money object. Exactly one of rate or amount_money should be set."

type SurchargeType

Indicates the source of the surcharge (CUSTOM or AUTO-GRATUITY). For example, if it was applied as an automatic gratuity for a large group.

taxable boolean

Indicates whether the surcharge is taxable.

taxes PaymentTax []

The list of taxes that should be applied to the surcharge.

surcharge_id string

A Square-issued unique identifier associated with the surcharge.

Refund

Represents a refund initiated by a Square merchant.

Fields

Name Type Description
type Refund.Type

The type of refund (FULL or PARTIAL).

reason string

The merchant-specified reason for the refund.

refunded_money Money

The amount of money refunded. This amount is always negative.

refunded_processing_fee_money Money

The amount of processing fee money refunded. This amount is always positive.

refunded_tax_money Money

The total amount of tax money refunded. This amount is always negative.

refunded_additive_tax_money Money

The amount of additive tax money refunded. This amount is always negative.

refunded_additive_tax PaymentTax []

All of the additive taxes associated with the refund.

refunded_inclusive_tax_money Money

The amount of inclusive tax money refunded. This amount is always negative.

refunded_inclusive_tax PaymentTax []

All of the inclusive taxes associated with the refund.

refunded_tip_money Money

The amount of tip money refunded. This amount is always negative.

refunded_discount_money Money

The amount of discount money refunded. This amount is always positive.

refunded_surcharge_money Money

The amount of surcharge money refunded. This amount is always negative.

return_surcharges PaymentSurcharge []

A list of all surcharges associated with the refund.

created_at string

The time when the merchant initiated the refund for Square to process, in ISO 8601 format.

processed_at string

The time when Square processed the refund on behalf of the merchant, in ISO 8601 format.

payment_id string

The Square-issued ID of the payment the refund is applied to.

For refunds to split-tender payments, payment_id instead is the tender's ID.

For exchange refunds (is_exchange == true), payment_id is the payment's ID, regardless of whether the payment has other tenders.

merchant_id string

The unique identifier of the merchant that took the payment.

is_exchange boolean

Indicates whether or not the refund is associated with an exchange. If true, this refund reflects the value of goods returned in the exchange, rather than actual money refunded.

Settlement

Represents a deposit or withdrawal made by Square to a merchant's bank account.

Fields

Name Type Description
id string

The settlement's unique identifier.

status Settlement.Status

The settlement's current status.

initiated_at string

The time when the settlement was submitted for deposit or withdrawal, in ISO 8601 format.

bank_account_id string

The Square-issued unique identifier for the bank account associated with the settlement.

total_money Money

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.

entries SettlementEntry []

The entries included in this settlement.

SettlementEntry

Represents a single entry in a Settlement .

Fields

Name Type Description
type SettlementEntry.Type

The type of activity this entry represents.

payment_id string

The payment associated with the settlement entry, if any.

amount_money Money

The total amount of money this entry contributes to the total settlement amount.

fee_money Money

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.

Tender

Represents a form and amount of tender provided for a payment. Multiple forms of tender can be provided for a single payment.

Fields

Name Type Description
id string

The tender's unique ID.

type Tender.Type

The type of tender.

name string

A human-readable description of the tender.

employee_id string

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_url string

The URL of the receipt for the tender.

card_brand Tender.CardBrand

The brand of credit card provided.

Only present if the tender's type is CREDIT_CARD.

pan_suffix string

The last four digits of the provided credit card's account number.

Only present if the tender's type is CREDIT_CARD.

entry_method Tender.EntryMethod

The method with which the tender was entered.

payment_note string

Notes entered by the merchant about the tender at the time of payment, if any. Typically only present for tender with the typeOTHER.

is_exchange boolean

Indicates whether or not the tender is associated with an exchange. If so, this tender represents the value of goods returned in an exchange, rather than actual money paid. This value reduces the amount of any other tenders needed to pay for itemizations purchased in the exchange.

total_money Money

The total amount of money provided in this form of tender.

tendered_money Money

The amount of total_money applied to the payment.

tendered_at string

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

settled_at string

The time when the tender was settled, in ISO 8601 format.

change_back_money Money

The amount of total_money returned to the buyer as change.

refunded_money Money

The total of all refunds applied to this tender. This amount is always negative or zero.

Timecard

Represents a timecard for an employee.

Fields

Name Type Description
id string

The timecard's unique ID.

employee_id string

The ID of the employee the timecard is associated with.

deleted boolean

If true, the timecard was deleted by the merchant, and it is no longer valid.

clockin_time string

The time the employee clocked in, in ISO 8601 format.

clockout_time string

The time the employee clocked out, in ISO 8601 format.

clockin_location_id string

The ID of the Location the employee clocked in from, if any. Square uses the clockin_location_id to determine a timecard’s timezone and overtime rules.

clockout_location_id string

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

regular_seconds_worked number

The total number of regular (non-overtime) seconds worked in the timecard.

overtime_seconds_worked number

The total number of overtime seconds worked in the timecard.

doubletime_seconds_worked number

The total number of doubletime seconds worked in the timecard.

created_at string

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

updated_at string

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

Name Type Description
id string

The event's unique ID.

event_type TimecardEvent.Type

The type of action performed on the timecard, such as CLOCKIN or API_CREATE.

clockin_time string

The time the employee clocked in, in ISO 8601 format.

clockout_time string

The time the employee clocked out, in ISO 8601 format.

created_at string

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

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
TAX

The fee is a tax.

Fee.CalculationPhase

Indicates whether a fee is calculated based on a payment's subtotal or total.

Value Description
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.
Value Description
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.

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
CREDIT_CARD_PROCESSING

The merchant can process credit cards with Square.

EMPLOYEE_MANAGEMENT

Applies to multi-location accounts. The merchant can add employees and manage employee roles and permissions.

TIMECARD_MANAGEMENT

Applies to multi-location accounts.The merchant can use timecards to track when their employees clock in and out.

ModifierList.SelectionType

Indicates whether more than one modifier option from a single modifier list can be applied to a single item.

Value Description
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.

Value Description

PaymentItemization.Type

The type of purchase that a payment itemization represents.

Value Description
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.

Value Description
FULL

A full refund.

PARTIAL

A partial refund.

PageCell.Type

The type of entity represented by a page cell.

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
FAILED

The settlement failed.

SENT

The settlement was sent for processing.

Surcharge.Type

Indicates the source of the surcharge. For example, if it was applied as an automatic gratuity for a large group.

Value Description
UNKNOWN

Placeholder for future functionality.

AUTO_GRATUITY

A non-negotiable percentage-based surcharge automatically applied to the purchase total.

CUSTOM

An ad hoc surcharge manually applied to the purchase total as a percentage or flat amount.

Tender.CardBrand

The brand of a credit card.

Value Description
OTHER_BRAND

Any card brand not covered by the other enum values.

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.

CHINA_UNIONPAY

A China UnionPay credit card.

SQUARE_GIFT_CARD

A Square gift card.

Tender.EntryMethod

The method with which a form of tender was entered.

Value Description
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.

Value Description
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.

Value Description
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.

Value Description
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.

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 are 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

Currently, Connect API has two major versions: V1 and V2 included in its path. Connect API applications can communicate with endpoints from all available versions. In Connect V2 API, Square-Version is supported for the evolutional changes. Please refer to How Versioning Works for more details.

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:

Action HTTP Method Description
Create POST Creates and persists an entity of the corresponding type.
List GET Returns 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.
Retrieve GET Provides comprehensive information for the single entity that matches the identifier you provide.
Update PUT Modifies the existing entity that matches the identifier you provide.
Delete DELETE Deletes 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:

Name Type Description
type string

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

message string

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)

Type Description
bad_request.missing_parameter A required parameter was missing from the request.
bad_request.invalid_parameter The request included an invalid parameter.
bad_request The request was otherwise malformed.

Unauthorized (401)

Type Description
service.not_authorized Your application is not authorized to make this request.
oauth.revoked Your application's access token was revoked.
oauth.expired Your application's access token has expired.

Forbidden (403)

Type Description
forbidden The requesting application does not have permission to access the resource, typically because the OAuth token's permission scope is insufficient.

Not Found (404)

Type Description
not_found The resource specified in the request wasn't found.

Unprocessable Entity (422)

Type Description
unprocessable_entity The 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)

Type Description
too_many_requests The 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)

Type Description
internal_server_error Square encountered an unexpected error processing the request.

Service Unavailable (503)

Type Description
service_unavailable The Connect API service is currently unavailable.