Connect API Technical Reference

Version 2019-04-10 Technical Reference Archive

Connect API Basics

v1 versus v2

Connect APIs come in 2 forms: Connect v2 and Connect v1.

The Connect v2 API suite supports online payments, order creation for itemized transactions, product catalog management, inventory management, and customer management.

The Connect v1 API suite supports webhooks and employee, role, and timecard management. Payment and item management functionality in the v1 suite is still fully supported but provided primarily for backward compatibility.

Connect v1 APIs, endpoints, data types, and enums are denoted with the prefix V1:

  • Business management endpoints for employees, timecards, and drawer shifts are organized under the V1Employees API.
  • Business management endpoints for locations and business information are organized under the V1Locations API.
  • Item management endpoints for catalog items, item categories, discounts, fees, and Square Point of Sale customization are organized under the V1Items API.
  • Transaction management endpoints for payments, settlements, refunds, and bank accounts are organized under the V1Transactions API.

Build with SDKs

Square offers SDKs in PHP, Ruby, Node.js, Java, .NET, and Python, to simplify development with Connect APIs. See the Square SDKs for a full list of available web and mobile SDKs.

Build with REST

Connect endpoints are hosted from the base URL https://connect.squareup.com and use v1 or v2 in the endpoint path to indicate whether they are in Connect v1 or Connect v2.

For example, the endpoint path for the the Connect v2 CreateOrder endpoint is /v2/locations/{location_id}/orders which makes the full endpoint URL:

connect.squareup.com/v2/locations/{location_id}/orders

Request headers

All REST requests to Connect API endpoints must include the following HTTP headers:

Authorization: Bearer SQ_ACCESS_TOKEN
Accept: application/json

where SQ_ACCESS_TOKEN is a valid Square access token.

POST and PUT requests must also include the following HTTP header:

Content-Type: application/json

Request parameters

GET and DELETE requests provide parameters in a URL-escaped query string appended to the request URL. For example, including the value 2016-01-15T00:00:00+02:00 as the begin_time parameter of the ListTransactions results in the following request URL:

https://connect.squareup.com/v2/locations/LOCATION_ID/transactions?begin_time=2016-01-15T00%3A00%3A00%2B02%3A00

POST and PUT requests provide parameters as JSON in the body of the request. For example, the body of a request to the CreateCustomer endpoint looks like:

{
  "given_name": "Amelia",
  "family_name": "Earhart"
}

Responses

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

Versioning

Square API versions (Square-Version) track changes in the evolution of Connect v2 APIs. The Square-Version naming scheme is YYYY-MM-DD, which indicates the date the version was released. Connect v1 APIs are not versioned. Square continues to support Connect v1, but future releases will focus on improving Connect v2 functionality.

By default, new Square applications are pinned to the version current at the time the application is created. Pinning an application sets the default Square-Version for the application. The default Square-Version of an application can be reviewed and updated at any time on the settings pages for the application.

See the Versioning Overview for more information.

This is a legacy reference for Connect API version 2019-04-10. View the current version >

Connect v2 APIs

If Square API endpoints receive too many requests associated with the same application ID or access token in a short time window, they might respond with a 429 Too Many Requests error, indicating that the application may try the request again at a later time.

RegisterDomain

POST /v2/apple-pay/domains

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

This endpoint provides an easy way for platform developers to bulk activate Web Apple Pay with Square for merchants using their platform.

To learn more about Apple Pay on Web see the Apple Pay section in the Embedding the Square Payment Form guide.

Body Parameters

Name Type Description
domain_name
(required)
string

A domain name as described in RFC-1034 that will be registered with ApplePay

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

status string

Status of the domain registration. See RegisterDomainResponseStatus for possible values

Example Request

POST /v2/apple-pay/domains

{
  "domain_name": "example.com"
}

Example Response

{
  "status": "VERIFIED"
}

BatchDeleteCatalogObjects

POST /v2/catalog/batch-delete

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

BatchDeleteCatalogObjects succeeds even if only a portion of the targeted IDs can be deleted. The response will only include IDs that were actually deleted.

Required permissions: ITEMS_WRITE

Body Parameters

Name Type Description
object_ids string[]

The IDs of the CatalogObjects to be deleted. When an object is deleted, other objects in the graph that depend on that object will be deleted as well (for example, deleting a CatalogItem will delete its CatalogItemVariations).

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

deleted_object_ids string[]

The IDs of all CatalogObjects deleted by this request.

deleted_at string

The database timestamp of this deletion in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z".

Example Request

POST /v2/catalog/batch-delete

{
  "object_ids": [
    "W62UWFY35CWMYGVWK6TWJDNI",
    "AA27W3M2GGTF3H6AVPNB77CK"
  ]
}

Example Response

{
  "deleted_object_ids": [
    "W62UWFY35CWMYGVWK6TWJDNI",
    "AA27W3M2GGTF3H6AVPNB77CK"
  ],
  "deleted_at": "2016-11-16T22:25:24.878Z"
}

BatchRetrieveCatalogObjects

POST /v2/catalog/batch-retrieve

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

Required permissions: ITEMS_READ

Body Parameters

Name Type Description
object_ids
(required)
string[]

The IDs of the CatalogObjects to be retrieved.

include_related_objects boolean

If true, the response will include additional objects that are related to the requested objects, as follows:

If the objects field of the response contains a CatalogItem, its associated CatalogCategory, CatalogTaxes, and CatalogModifierLists will be returned in the related_objects field of the response. If the objects field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in the related_objects field of the response.

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

objects CatalogObject[]

A list of CatalogObjects returned.

related_objects CatalogObject[]

A list of CatalogObjects referenced by the object in the objects field.

Example Request

POST /v2/catalog/batch-retrieve

{
  "object_ids": [
    "W62UWFY35CWMYGVWK6TWJDNI",
    "AA27W3M2GGTF3H6AVPNB77CK"
  ],
  "include_related_objects": true
}

Example Response

{
  "objects": [
    {
      "type": "ITEM",
      "id": "W62UWFY35CWMYGVWK6TWJDNI",
      "updated_at": "2016-11-16T22:25:24.878Z",
      "version": 1479335124878,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "Tea",
        "description": "Hot Leaf Juice",
        "category_id": "BJNQCF2FJ6S6UIDT65ABHLRX",
        "tax_ids": [
          "HURXQOOAIC4IZSI2BEXQRYFY"
        ],
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "2TZFAOHWGG7PAK2QEXWYPZSP",
            "updated_at": "2016-11-16T22:25:24.878Z",
            "version": 1479335124878,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "W62UWFY35CWMYGVWK6TWJDNI",
              "name": "Mug",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 150,
                "currency": "USD"
              }
            }
          }
        ]
      }
    },
    {
      "type": "ITEM",
      "id": "AA27W3M2GGTF3H6AVPNB77CK",
      "updated_at": "2016-11-16T22:25:24.878Z",
      "version": 1479335124878,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "Coffee",
        "description": "Hot Bean Juice",
        "category_id": "BJNQCF2FJ6S6UIDT65ABHLRX",
        "tax_ids": [
          "HURXQOOAIC4IZSI2BEXQRYFY"
        ],
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "LBTYIHNHU52WOIHWT7SNRIYH",
            "updated_at": "2016-11-16T22:25:24.878Z",
            "version": 1479335124878,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "AA27W3M2GGTF3H6AVPNB77CK",
              "name": "Regular",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 250,
                "currency": "USD"
              }
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "PKYIC7HGGKW5CYVSCVDEIMHY",
            "updated_at": "2016-11-16T22:25:24.878Z",
            "version": 1479335124878,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "AA27W3M2GGTF3H6AVPNB77CK",
              "name": "Large",
              "ordinal": 1,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 350,
                "currency": "USD"
              }
            }
          }
        ]
      }
    }
  ],
  "related_objects": [
    {
      "type": "CATEGORY",
      "id": "BJNQCF2FJ6S6UIDT65ABHLRX",
      "updated_at": "2016-11-16T22:25:24.878Z",
      "version": 1479335124878,
      "is_deleted": false,
      "present_at_all_locations": true,
      "category_data": {
        "name": "Beverages"
      }
    },
    {
      "type": "TAX",
      "id": "HURXQOOAIC4IZSI2BEXQRYFY",
      "updated_at": "2016-11-16T22:25:24.878Z",
      "version": 1479335124878,
      "is_deleted": false,
      "present_at_all_locations": true,
      "tax_data": {
        "name": "Sales Tax",
        "calculation_phase": "TAX_SUBTOTAL_PHASE",
        "inclusion_type": "ADDITIVE",
        "percentage": "5.0",
        "enabled": true
      }
    }
  ]
}

BatchUpsertCatalogObjects

POST /v2/catalog/batch-upsert

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

Required permissions: ITEMS_WRITE

Body Parameters

Name Type Description
idempotency_key
(required)
string

A value you specify that uniquely identifies this request among all your requests. A common way to create a valid idempotency key is to use a Universally unique identifier (UUID).

If you're unsure whether a particular request was successful, you can reattempt it with the same idempotency key without worrying about creating duplicate objects.

See Idempotency for more information.

batches CatalogObjectBatch[]

A batch of CatalogObjects to be inserted/updated atomically. The objects within a batch will be inserted in an all-or-nothing fashion, i.e., if an error occurs attempting to insert or update an object within a batch, the entire batch will be rejected. However, an error in one batch will not affect other batches within the same request.

For each object, its updated_at field is ignored and replaced with a current timestamp, and its is_deleted field must not be set to true.

To modify an existing object, supply its ID. To create a new object, use an ID starting with #. These IDs may be used to create relationships between an object and attributes of other objects that reference it. For example, you can create a CatalogItem with ID #ABC and a CatalogItemVariation with its item_id attribute set to #ABC in order to associate the CatalogItemVariation with its parent CatalogItem.

Any #-prefixed IDs are valid only within a single atomic batch, and will be replaced by server-generated IDs.

Each batch may contain up to 1,000 objects. The total number of objects across all batches for a single request may not exceed 10,000. If either of these limits is violated, an error will be returned and no objects will be inserted or updated.

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

objects CatalogObject[]

The created CatalogObjects

updated_at string

The database timestamp of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z".

id_mappings CatalogIdMapping[]

The mapping between client and server IDs for this Upsert.

Example Request

POST /v2/catalog/batch-upsert

{
  "idempotency_key": "789ff020-f723-43a9-b4b5-43b5dc1fa3dc",
  "batches": [
    {
      "objects": [
        {
          "type": "ITEM",
          "id": "#Tea",
          "present_at_all_locations": true,
          "item_data": {
            "name": "Tea",
            "description": "Hot Leaf Juice",
            "category_id": "#Beverages",
            "tax_ids": [
              "#SalesTax"
            ],
            "variations": [
              {
                "type": "ITEM_VARIATION",
                "id": "#Tea_Mug",
                "present_at_all_locations": true,
                "item_variation_data": {
                  "item_id": "#Tea",
                  "name": "Mug",
                  "pricing_type": "FIXED_PRICING",
                  "price_money": {
                    "amount": 150,
                    "currency": "USD"
                  }
                }
              }
            ]
          }
        },
        {
          "type": "ITEM",
          "id": "#Coffee",
          "present_at_all_locations": true,
          "item_data": {
            "name": "Coffee",
            "description": "Hot Bean Juice",
            "category_id": "#Beverages",
            "tax_ids": [
              "#SalesTax"
            ],
            "variations": [
              {
                "type": "ITEM_VARIATION",
                "id": "#Coffee_Regular",
                "present_at_all_locations": true,
                "item_variation_data": {
                  "item_id": "#Coffee",
                  "name": "Regular",
                  "pricing_type": "FIXED_PRICING",
                  "price_money": {
                    "amount": 250,
                    "currency": "USD"
                  }
                }
              },
              {
                "type": "ITEM_VARIATION",
                "id": "#Coffee_Large",
                "present_at_all_locations": true,
                "item_variation_data": {
                  "item_id": "#Coffee",
                  "name": "Large",
                  "pricing_type": "FIXED_PRICING",
                  "price_money": {
                    "amount": 350,
                    "currency": "USD"
                  }
                }
              }
            ]
          }
        },
        {
          "type": "CATEGORY",
          "id": "#Beverages",
          "present_at_all_locations": true,
          "category_data": {
            "name": "Beverages"
          }
        },
        {
          "type": "TAX",
          "id": "#SalesTax",
          "present_at_all_locations": true,
          "tax_data": {
            "name": "Sales Tax",
            "calculation_phase": "TAX_SUBTOTAL_PHASE",
            "inclusion_type": "ADDITIVE",
            "percentage": "5.0",
            "applies_to_custom_amounts": true,
            "enabled": true
          }
        }
      ]
    }
  ]
}

Example Response

{
  "objects": [
    {
      "type": "ITEM",
      "id": "ZSDZN34NAXDLC6D5ZQMNSOUM",
      "updated_at": "2017-05-10T18:48:39.798Z",
      "version": 1494442119798,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "Tea",
        "description": "Hot Leaf Juice",
        "category_id": "LYT72K3WGJFFCIMB63XARP3I",
        "tax_ids": [
          "XHSHLHNWSI3HVI4BW5ZUZXI3"
        ],
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "NAYHET5R52MIYCEF34ZMAHFM",
            "updated_at": "2017-05-10T18:48:39.798Z",
            "version": 1494442119798,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "ZSDZN34NAXDLC6D5ZQMNSOUM",
              "name": "Mug",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 150,
                "currency": "USD"
              }
            }
          }
        ]
      }
    },
    {
      "type": "ITEM",
      "id": "PJMCEBHHUS3OKDB6PYUHLCPP",
      "updated_at": "2017-05-10T18:48:39.798Z",
      "version": 1494442119798,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "Coffee",
        "description": "Hot Bean Juice",
        "category_id": "LYT72K3WGJFFCIMB63XARP3I",
        "tax_ids": [
          "XHSHLHNWSI3HVI4BW5ZUZXI3"
        ],
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "OTYDX45SPG7LJQUVCBZI4INH",
            "updated_at": "2017-05-10T18:48:39.798Z",
            "version": 1494442119798,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "PJMCEBHHUS3OKDB6PYUHLCPP",
              "name": "Regular",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 250,
                "currency": "USD"
              }
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "GZDA3JB37FYVOPI4AOEBOITI",
            "updated_at": "2017-05-10T18:48:39.798Z",
            "version": 1494442119798,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "PJMCEBHHUS3OKDB6PYUHLCPP",
              "name": "Large",
              "ordinal": 1,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 350,
                "currency": "USD"
              }
            }
          }
        ]
      }
    },
    {
      "type": "CATEGORY",
      "id": "LYT72K3WGJFFCIMB63XARP3I",
      "updated_at": "2017-05-10T18:48:39.798Z",
      "version": 1494442119798,
      "is_deleted": false,
      "present_at_all_locations": true,
      "category_data": {
        "name": "Beverages"
      }
    },
    {
      "type": "TAX",
      "id": "XHSHLHNWSI3HVI4BW5ZUZXI3",
      "updated_at": "2017-05-10T18:48:39.798Z",
      "version": 1494442119798,
      "is_deleted": false,
      "present_at_all_locations": true,
      "tax_data": {
        "name": "Sales Tax",
        "calculation_phase": "TAX_SUBTOTAL_PHASE",
        "inclusion_type": "ADDITIVE",
        "percentage": "5.0",
        "applies_to_custom_amounts": true,
        "enabled": true
      }
    }
  ],
  "id_mappings": [
    {
      "client_object_id": "#Tea",
      "object_id": "ZSDZN34NAXDLC6D5ZQMNSOUM"
    },
    {
      "client_object_id": "#Coffee",
      "object_id": "PJMCEBHHUS3OKDB6PYUHLCPP"
    },
    {
      "client_object_id": "#Beverages",
      "object_id": "LYT72K3WGJFFCIMB63XARP3I"
    },
    {
      "client_object_id": "#SalesTax",
      "object_id": "XHSHLHNWSI3HVI4BW5ZUZXI3"
    },
    {
      "client_object_id": "#Tea_Mug",
      "object_id": "NAYHET5R52MIYCEF34ZMAHFM"
    },
    {
      "client_object_id": "#Coffee_Regular",
      "object_id": "OTYDX45SPG7LJQUVCBZI4INH"
    },
    {
      "client_object_id": "#Coffee_Large",
      "object_id": "GZDA3JB37FYVOPI4AOEBOITI"
    }
  ]
}

CatalogInfo

GET /v2/catalog/info

Returns information about the Square Catalog API, such as batch size limits for BatchUpsertCatalogObjects.

Required permissions: ITEMS_READ

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

limits CatalogInfoResponseLimits

Example Request

GET /v2/catalog/info

Example Response

{
  "limits": {
    "batch_upsert_max_objects_per_batch": 1000,
    "batch_upsert_max_total_objects": 10000,
    "batch_retrieve_max_object_ids": 1000,
    "search_max_page_limit": 1000,
    "batch_delete_max_object_ids": 200,
    "update_item_taxes_max_item_ids": 1000,
    "update_item_taxes_max_taxes_to_enable": 1000,
    "update_item_taxes_max_taxes_to_disable": 1000,
    "update_item_modifier_lists_max_item_ids": 1000,
    "update_item_modifier_lists_max_modifier_lists_to_enable": 1000,
    "update_item_modifier_lists_max_modifier_lists_to_disable": 1000
  }
}

CreateCatalogImage

POST /v2/catalog/images

Upload an image file to create a new CatalogImage for an existing CatalogObject. Images can be uploaded and linked in this request or created independently (without an object assignment) and linked to a CatalogObject at a later time.

CreateCatalogImage accepts HTTP multipart/form-data requests with a JSON part and an image file part in JPEG, PJPEG, PNG, or GIF format. The following is an example of such an HTTP request:

POST /v2/catalog/images
Accept: application/json
Content-Type: multipart/form-data;boundary="boundary"
Square-Version: XXXX-XX-XX
Authorization: Bearer {ACCESS_TOKEN}

--boundary
Content-Disposition: form-data; name="request"
Content-Type: application/json

{
"idempotency_key":"528dea59-7bfb-43c1-bd48-4a6bba7dd61f86",
"object_id": "ND6EA5AAJEO5WL3JNNIAQA32",
"image":{
"id":"#TEMP_ID",
"type":"IMAGE",
"image_data":{
"caption":"A picture of a cup of coffee"
}
}
}
--boundary
Content-Disposition: form-data; name="image"; filename="Coffee.jpg"
Content-Type: image/jpeg

{ACTUAL_IMAGE_BYTES}
--boundary

Additional information and an example cURL request can be found in the Create a Catalog Image recipe.

Required permissions: ITEMS_WRITE

Body Parameters

Name Type Description
idempotency_key
(required)
string

A unique string that identifies this CreateCatalogImage request. Keys can be any valid string but must be unique for every CreateCatalogImage request.

See Idempotency keys for more information.

object_id string

Unique ID of the CatalogObject to attach to this CatalogImage. Leave this field empty to create unattached images, for example if you are building an integration where these images can be attached to catalog items at a later time.

image CatalogObject

The new IMAGE-type CatalogObject to be attached to this CatalogImage. If the CatalogObject already has a CatalogImage, this call will overwrite it.

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

image CatalogObject

The newly created CatalogImage including a URL generated by Square for each image.

Example Request

POST /v2/catalog/images

{
  "idempotency_key": "528dea59-7bfb-43c1-bd48-4a6bba7dd61f86",
  "object_id": "ND6EA5AAJEO5WL3JNNIAQA32",
  "image": {
    "id": "#TEMP_ID",
    "type": "IMAGE",
    "image_data": {
      "caption": "A picture of a cup of coffee"
    }
  }
}

DeleteCatalogObject

DELETE /v2/catalog/object/{object_id}

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

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
object_id
(required)
string

The ID of the CatalogObject to be deleted. When an object is deleted, other objects in the graph that depend on that object will be deleted as well (for example, deleting a CatalogItem will delete its CatalogItemVariations).

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

deleted_object_ids string[]

The IDs of all CatalogObjects deleted by this request. Multiple IDs may be returned when associated objects are also deleted, for example a CatalogItemVariation will be deleted (and its ID included in this field) when its parent CatalogItem is deleted.

deleted_at string

The database timestamp of this deletion in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z".

Example Request

DELETE /v2/catalog/object/{object_id}

Example Response

{
  "deleted_object_ids": [
    "7SB3ZQYJ5GDMVFL7JK46JCHT",
    "KQLFFHA6K6J3YQAQAWDQAL57"
  ],
  "deleted_at": "2016-11-16T22:25:24.878Z"
}

ListCatalog

GET /v2/catalog/list

Returns a list of CatalogObjects that includes all objects of a set of desired types (for example, all CatalogItem and CatalogTax objects) in the catalog. The types parameter is specified as a comma-separated list of valid CatalogObject types: ITEM, ITEM_VARIATION, MODIFIER, MODIFIER_LIST, CATEGORY, DISCOUNT, TAX.

Required permissions: ITEMS_READ

Query Parameters

Name Type Description
cursor string

The pagination cursor returned in the previous response. Leave unset for an initial request. See Pagination for more information.

types string

An optional case-insensitive, comma-separated list of object types to retrieve, for example ITEM,ITEM_VARIATION,CATEGORY,IMAGE.

The legal values are taken from the CatalogObjectType enumeration, namely ITEM, ITEM_VARIATION, CATEGORY, DISCOUNT, TAX, MODIFIER, MODIFIER_LIST, or IMAGE.

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

cursor string

The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Pagination for more information.

objects CatalogObject[]

The CatalogObjects returned.

Example Request

GET /v2/catalog/list?types=category,tax

Example Response

{
  "objects": [
    {
      "type": "CATEGORY",
      "id": "5ZYQZZ2IECPVJ2IJ5KQPRDC3",
      "updated_at": "2017-02-21T14:50:26.495Z",
      "version": 1487688626495,
      "is_deleted": false,
      "present_at_all_locations": true,
      "category_data": {
        "name": "Beverages"
      }
    },
    {
      "type": "TAX",
      "id": "L5R47DGBZOOVKCAFIXC56AEN",
      "updated_at": "2017-02-21T14:50:26.495Z",
      "version": 1487688626495,
      "is_deleted": false,
      "present_at_all_locations": true,
      "tax_data": {
        "name": "Sales Tax",
        "calculation_phase": "TAX_SUBTOTAL_PHASE",
        "inclusion_type": "ADDITIVE",
        "percentage": "5.0",
        "enabled": true
      }
    }
  ]
}

RetrieveCatalogObject

GET /v2/catalog/object/{object_id}

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

Required permissions: ITEMS_READ

Path Parameters

Name Type Description
object_id
(required)
string

The object ID of any type of CatalogObjects to be retrieved.

Query Parameters

Name Type Description
include_related_objects boolean

If true, the response will include additional objects that are related to the requested object, as follows:

If the object field of the response contains a CatalogItem, its associated CatalogCategory, CatalogTaxes, and CatalogModifierLists will be returned in the related_objects field of the response. If the object field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in the related_objects field of the response.

Default value: false

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

object CatalogObject

The CatalogObjects returned.

related_objects CatalogObject[]

A list of CatalogObjects referenced by the object in the object field.

Example Request

GET /v2/catalog/object/{object_id}?include_related_objects=true

Example Response

{
  "object": {
    "type": "ITEM",
    "id": "W62UWFY35CWMYGVWK6TWJDNI",
    "updated_at": "2016-11-16T22:25:24.878Z",
    "version": 1479335124878,
    "is_deleted": false,
    "present_at_all_locations": true,
    "item_data": {
      "name": "Tea",
      "description": "Hot Leaf Juice",
      "category_id": "BJNQCF2FJ6S6UIDT65ABHLRX",
      "tax_ids": [
        "HURXQOOAIC4IZSI2BEXQRYFY"
      ],
      "variations": [
        {
          "type": "ITEM_VARIATION",
          "id": "2TZFAOHWGG7PAK2QEXWYPZSP",
          "updated_at": "2016-11-16T22:25:24.878Z",
          "version": 1479335124878,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "W62UWFY35CWMYGVWK6TWJDNI",
            "name": "Mug",
            "ordinal": 0,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 150,
              "currency": "USD"
            }
          }
        }
      ]
    }
  },
  "related_objects": [
    {
      "type": "CATEGORY",
      "id": "BJNQCF2FJ6S6UIDT65ABHLRX",
      "updated_at": "2016-11-16T22:25:24.878Z",
      "version": 1479335124878,
      "is_deleted": false,
      "present_at_all_locations": true,
      "category_data": {
        "name": "Beverages"
      }
    },
    {
      "type": "TAX",
      "id": "HURXQOOAIC4IZSI2BEXQRYFY",
      "updated_at": "2016-11-16T22:25:24.878Z",
      "version": 1479335124878,
      "is_deleted": false,
      "present_at_all_locations": true,
      "tax_data": {
        "name": "Sales Tax",
        "calculation_phase": "TAX_SUBTOTAL_PHASE",
        "inclusion_type": "ADDITIVE",
        "percentage": "5.0",
        "enabled": true
      }
    }
  ]
}

SearchCatalogObjects

POST /v2/catalog/search

Queries the targeted catalog using a variety of query types: CatalogQuerySortedAttribute, CatalogQueryExact, CatalogQueryRange, CatalogQueryText, CatalogQueryItemsForTax, and CatalogQueryItemsForModifierList.

Required permissions: ITEMS_READ

Body Parameters

Name Type Description
cursor string

The pagination cursor returned in the previous response. Leave unset for an initial request. See Pagination for more information.

object_types string[]

The desired set of object types to appear in the search results. The legal values are taken from the CatalogObjectType enumeration, namely "ITEM", "ITEM_VARIATION", "CATEGORY", "DISCOUNT", "TAX", "MODIFIER", or "MODIFIER_LIST". See CatalogObjectType for possible values

include_deleted_objects boolean

If true, deleted objects will be included in the results. Deleted objects will have their is_deleted field set to true.

include_related_objects boolean

If true, the response will include additional objects that are related to the requested object, as follows:

If a CatalogItem is returned in the object field of the response, its associated CatalogCategory, CatalogTaxes, and CatalogModifierLists will be included in the related_objects field of the response.

If a CatalogItemVariation is returned in the object field of the response, its parent CatalogItem will be included in the related_objects field of the response.

begin_time string

Return objects modified after this timestamp, in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". The timestamp is exclusive - objects with a timestamp equal to begin_time will not be included in the response.

query CatalogQuery

A query to be used to filter or sort the results. If no query is specified, the entire catalog will be returned.

limit integer

A limit on the number of results to be returned in a single page. The limit is advisory - the implementation may return more or fewer results. If the supplied limit is negative, zero, or is higher than the maximum limit of 1,000, it will be ignored.

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

cursor string

The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Pagination for more information.

objects CatalogObject[]

The CatalogObjects returned.

related_objects CatalogObject[]

A list of CatalogObjects referenced by the objects in the objects field.

Example Request

POST /v2/catalog/search

{
  "object_types": [
    "ITEM"
  ],
  "query": {
    "prefix_query": {
      "attribute_name": "name",
      "attribute_prefix": "tea"
    }
  },
  "limit": 100
}

Example Response

{
  "objects": [
    {
      "type": "ITEM",
      "id": "X5DZ5NWWAQ44CKBLKIFQGOWK",
      "updated_at": "2017-10-26T15:41:32.337Z",
      "version": 1509032492337,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "Tea - Black",
        "description": "A delicious blend of black tea.",
        "category_id": "E7CLE5RZZ744BHWVQQEAHI2C",
        "product_type": "REGULAR",
        "tax_ids": [
          "ZXITPM6RWHZ7GZ7EIP3YKECM"
        ],
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "5GSZPX6EU7MM75S57OONG3V5",
            "updated_at": "2017-10-26T15:27:31.626Z",
            "version": 1509031651626,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "X5DZ5NWWAQ44CKBLKIFQGOWK",
              "name": "Regular",
              "ordinal": 1,
              "price_money": {
                "amount": 150,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "XVLBN7DU6JTWHJTG5F265B43",
            "updated_at": "2017-10-26T15:27:31.626Z",
            "version": 1509031651626,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "X5DZ5NWWAQ44CKBLKIFQGOWK",
              "name": "Large",
              "ordinal": 2,
              "price_money": {
                "amount": 225,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          }
        ],
        "visibility": "PRIVATE"
      }
    },
    {
      "type": "ITEM",
      "id": "NNNEM3LA656Q46NXLWCNI7S5",
      "updated_at": "2017-10-26T15:41:23.232Z",
      "version": 1509032483232,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "Tea - Green",
        "description": "Relaxing green herbal tea.",
        "category_id": "E7CLE5RZZ744BHWVQQEAHI2C",
        "product_type": "REGULAR",
        "tax_ids": [
          "ZXITPM6RWHZ7GZ7EIP3YKECM"
        ],
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "FHYBVIA6NVBCSOVETA62WEA4",
            "updated_at": "2017-10-26T15:29:00.524Z",
            "version": 1509031740524,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "NNNEM3LA656Q46NXLWCNI7S5",
              "name": "Regular",
              "ordinal": 1,
              "price_money": {
                "amount": 150,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          }
        ],
        "visibility": "PRIVATE"
      }
    }
  ]
}

UpdateItemModifierLists

POST /v2/catalog/update-item-modifier-lists

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

Required permissions: ITEMS_WRITE

Body Parameters

Name Type Description
item_ids
(required)
string[]

The CatalogItems whose CatalogModifierLists are being updated.

modifier_lists_to_enable string[]

The set of CatalogModifierLists (referenced by ID) to enable for the CatalogItem.

modifier_lists_to_disable string[]

The set of CatalogModifierLists (referenced by ID) to disable for the CatalogItem.

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

updated_at string

The database timestamp of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z".

Example Request

POST /v2/catalog/update-item-modifier-lists

{
  "item_ids": [
    "H42BRLUJ5KTZTTMPVSLFAACQ",
    "2JXOBJIHCWBQ4NZ3RIXQGJA6"
  ],
  "modifier_lists_to_enable": [
    "H42BRLUJ5KTZTTMPVSLFAACQ",
    "2JXOBJIHCWBQ4NZ3RIXQGJA6"
  ],
  "modifier_lists_to_disable": [
    "7WRC16CJZDVLSNDQ35PP6YAD"
  ]
}

Example Response

{
  "updated_at": "2016-11-16T22:25:24.878Z"
}

UpdateItemTaxes

POST /v2/catalog/update-item-taxes

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

Required permissions: ITEMS_WRITE

Body Parameters

Name Type Description
item_ids
(required)
string[]

The CatalogItems whose enabled/disabled CatalogTaxes are being updated.

taxes_to_enable string[]

The set of CatalogTaxes (referenced by ID) to enable for the CatalogItem.

taxes_to_disable string[]

The set of CatalogTaxes (referenced by ID) to disable for the CatalogItem.

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

updated_at string

The database timestamp of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z".

Example Request

POST /v2/catalog/update-item-taxes

{
  "item_ids": [
    "H42BRLUJ5KTZTTMPVSLFAACQ",
    "2JXOBJIHCWBQ4NZ3RIXQGJA6"
  ],
  "taxes_to_enable": [
    "4WRCNHCJZDVLSNDQ35PP6YAD"
  ],
  "taxes_to_disable": [
    "AQCEGCEBBQONINDOHRGZISEX"
  ]
}

Example Response

{
  "updated_at": "2016-11-16T22:25:24.878Z"
}

UpsertCatalogObject

POST /v2/catalog/object

Creates or updates the target CatalogObject.

Required permissions: ITEMS_WRITE

Body Parameters

Name Type Description
idempotency_key
(required)
string

A value you specify that uniquely identifies this request among all your requests. A common way to create a valid idempotency key is to use a Universally unique identifier (UUID).

If you're unsure whether a particular request was successful, you can reattempt it with the same idempotency key without worrying about creating duplicate objects.

See Idempotency for more information.

object
(required)
CatalogObject

A CatalogObject to be created or updated.

  • For updates, the object must be active (the is_deleted field is not true).
  • For creates, the object ID must start with #. The provided ID is replaced with a server-generated ID.

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

catalog_object CatalogObject

The created CatalogObject.

id_mappings CatalogIdMapping[]

The mapping between client and server IDs for this Upsert.

Example Request

POST /v2/catalog/object

{
  "idempotency_key": "af3d1afc-7212-4300-b463-0bfc5314a5ae",
  "object": {
    "type": "ITEM",
    "id": "#Cocoa",
    "item_data": {
      "name": "Cocoa",
      "description": "Hot chocolate",
      "abbreviation": "Ch"
    }
  }
}

Example Response

{
  "catalog_object": {
    "type": "ITEM",
    "id": "7SB3ZQYJ5GDMVFL7JK46JCHT",
    "updated_at": "2016-11-16T22:32:42.996Z",
    "version": 1479335562996,
    "is_deleted": false,
    "item_data": {
      "name": "Cocoa",
      "description": "Hot chocolate",
      "abbreviation": "Ch"
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#Cocoa",
      "object_id": "7SB3ZQYJ5GDMVFL7JK46JCHT"
    }
  ]
}

CreateCheckout

POST /v2/locations/{location_id}/checkouts

Links a checkoutId to a checkout_page_url that customers will be directed to in order to provide their payment information using a payment processing workflow hosted on connect.squareup.com.

Required permissions: PAYMENTS_WRITE ORDERS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the business location to associate the checkout with.

Body Parameters

Name Type Description
idempotency_key
(required)
string

A unique string that identifies this checkout among others you've created. It can be any valid string but must be unique for every order sent to Square Checkout for a given location ID.

The idempotency key is used to avoid processing the same order more than once. If you're unsure whether a particular checkout was created successfully, you can reattempt it with the same idempotency key and all the same other parameters without worrying about creating duplicates.

We recommend using a random number/string generator native to the language you are working in to generate strings for your idempotency keys.

See Idempotency for more information.

order
(required)
CreateOrderRequest

The order including line items to be checked out.

ask_for_shipping_address boolean

If true, Square Checkout will collect shipping information on your behalf and store that information with the transaction information in your Square Dashboard.

Default: false.

merchant_support_email string

The email address to display on the Square Checkout confirmation page and confirmation email that the buyer can use to contact the merchant.

If this value is not set, the confirmation page and email will display the primary email address associated with the merchant's Square account.

Default: none; only exists if explicitly set.

pre_populate_buyer_email string

If provided, the buyer's email is pre-populated on the checkout page as an editable text field.

Default: none; only exists if explicitly set.

pre_populate_shipping_address Address

If provided, the buyer's shipping info is pre-populated on the checkout page as editable text fields.

Default: none; only exists if explicitly set.

redirect_url string

The URL to redirect to after checkout is completed with checkoutId, Square's orderId, transactionId, and referenceId appended as URL parameters. For example, if the provided redirect_url is http://www.example.com/order-complete, a successful transaction redirects the customer to:

http://www.example.com/order-complete?checkoutId=xxxxxx&orderId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx

If you do not provide a redirect URL, Square Checkout will display an order confirmation page on your behalf; however Square strongly recommends that you provide a redirect URL so you can verify the transaction results and finalize the order through your existing/normal confirmation workflow.

Default: none; only exists if explicitly set.

additional_recipients ChargeRequestAdditionalRecipient[]

The basic primitive of multi-party transaction. The value is optional. The transaction facilitated by you can be split from here.

If you provide this value, the amount_money value in your additional_recipients must not be more than 90% of the total_money calculated by Square for your order. The location_id must be the valid location of the app owner merchant.

This field requires PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission.

This field is currently not supported in sandbox.

note string

An optional note to associate with the checkout object.

This value cannot exceed 60 characters.

Response fields

Name Type Description
checkout Checkout

The newly created checkout. If the same request was made with the same idempotency_key, this will be the checkout created with the idempotency_key.

errors Error[]

Any errors that occurred during the request.

Example Request

POST /v2/locations/{location_id}/checkouts

{
  "idempotency_key": "86ae1696-b1e3-4328-af6d-f1e04d947ad6",
  "order": {
    "reference_id": "reference_id",
    "line_items": [
      {
        "name": "Printed T Shirt",
        "quantity": "2",
        "base_price_money": {
          "amount": 1500,
          "currency": "USD"
        },
        "discounts": [
          {
            "name": "7% off previous season item",
            "percentage": "7"
          },
          {
            "name": "$3 off Customer Discount",
            "amount_money": {
              "amount": 300,
              "currency": "USD"
            }
          }
        ]
      },
      {
        "name": "Slim Jeans",
        "quantity": "1",
        "base_price_money": {
          "amount": 2500,
          "currency": "USD"
        }
      },
      {
        "name": "Woven Sweater",
        "quantity": "3",
        "base_price_money": {
          "amount": 3500,
          "currency": "USD"
        },
        "discounts": [
          {
            "name": "$11 off Customer Discount",
            "amount_money": {
              "amount": 1100,
              "currency": "USD"
            }
          }
        ],
        "taxes": [
          {
            "name": "Fair Trade Tax",
            "percentage": "5"
          }
        ]
      }
    ],
    "discounts": [
      {
        "name": "Father's day 12% OFF",
        "percentage": "12"
      },
      {
        "name": "Global Sales $55 OFF",
        "amount_money": {
          "amount": 5500,
          "currency": "USD"
        }
      }
    ],
    "taxes": [
      {
        "name": "Sales Tax",
        "percentage": "8.5"
      }
    ]
  },
  "additional_recipients": [
    {
      "location_id": "057P5VYJ4A5X1",
      "description": "Application fees",
      "amount_money": {
        "amount": 60,
        "currency": "USD"
      }
    }
  ],
  "ask_for_shipping_address": true,
  "merchant_support_email": "[email protected]",
  "pre_populate_buyer_email": "[email protected]",
  "pre_populate_shipping_address": {
    "address_line_1": "1455 Market St.",
    "address_line_2": "Suite 600",
    "locality": "San Francisco",
    "administrative_district_level_1": "CA",
    "postal_code": "94103",
    "country": "US",
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "redirect_url": "https://merchant.website.com/order-confirm"
}

Example Response

{
  "checkout": {
    "id": "CAISEHGimXh-C3RIT4og1a6u1qw",
    "checkout_page_url": "https://connect.squareup.com/v2/checkout?c=CAISEHGimXh-C3RIT4og1a6u1qw&l=CYTKRM7R7JMV8",
    "ask_for_shipping_address": true,
    "merchant_support_email": "[email protected]",
    "pre_populate_buyer_email": "[email protected]",
    "pre_populate_shipping_address": {
      "address_line_1": "1455 Market St.",
      "address_line_2": "Suite 600",
      "locality": "San Francisco",
      "administrative_district_level_1": "CA",
      "postal_code": "94103",
      "country": "US",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "redirect_url": "https://merchant.website.com/order-confirm",
    "order": {
      "location_id": "CYTKRM7R7JMV8",
      "reference_id": "reference_id",
      "line_items": [
        {
          "name": "Printed T Shirt",
          "quantity": "2",
          "taxes": [
            {
              "name": "Sales Tax",
              "type": "ADDITIVE",
              "percentage": "8.5",
              "applied_money": {
                "amount": 103,
                "currency": "USD"
              }
            }
          ],
          "discounts": [
            {
              "name": "7% off previous season item",
              "type": "FIXED_PERCENTAGE",
              "percentage": "7",
              "applied_money": {
                "amount": 210,
                "currency": "USD"
              },
              "scope": "LINE_ITEM"
            },
            {
              "name": "Father's day 12% OFF",
              "type": "FIXED_PERCENTAGE",
              "percentage": "12",
              "applied_money": {
                "amount": 335,
                "currency": "USD"
              },
              "scope": "ORDER"
            },
            {
              "name": "$3 off Customer Discount",
              "type": "FIXED_AMOUNT",
              "amount_money": {
                "amount": 300,
                "currency": "USD"
              },
              "applied_money": {
                "amount": 300,
                "currency": "USD"
              },
              "scope": "LINE_ITEM"
            },
            {
              "name": "Global Sales $55 OFF",
              "type": "FIXED_AMOUNT",
              "amount_money": {
                "amount": 5500,
                "currency": "USD"
              },
              "applied_money": {
                "amount": 949,
                "currency": "USD"
              },
              "scope": "ORDER"
            }
          ],
          "base_price_money": {
            "amount": 1500,
            "currency": "USD"
          },
          "total_tax_money": {
            "amount": 103,
            "currency": "USD"
          },
          "total_discount_money": {
            "amount": 1794,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1309,
            "currency": "USD"
          }
        },
        {
          "name": "Slim Jeans",
          "quantity": "1",
          "taxes": [
            {
              "name": "Sales Tax",
              "type": "ADDITIVE",
              "percentage": "8.5",
              "applied_money": {
                "amount": 105,
                "currency": "USD"
              }
            }
          ],
          "discounts": [
            {
              "name": "Father's day 12% OFF",
              "type": "FIXED_PERCENTAGE",
              "percentage": "12",
              "applied_money": {
                "amount": 300,
                "currency": "USD"
              },
              "scope": "ORDER"
            },
            {
              "name": "Global Sales $55 OFF",
              "type": "FIXED_AMOUNT",
              "amount_money": {
                "amount": 5500,
                "currency": "USD"
              },
              "applied_money": {
                "amount": 968,
                "currency": "USD"
              },
              "scope": "ORDER"
            }
          ],
          "base_price_money": {
            "amount": 2500,
            "currency": "USD"
          },
          "total_tax_money": {
            "amount": 105,
            "currency": "USD"
          },
          "total_discount_money": {
            "amount": 1268,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1337,
            "currency": "USD"
          }
        },
        {
          "name": "Wooven Sweater",
          "quantity": "3",
          "taxes": [
            {
              "name": "Fair Trade Tax",
              "type": "ADDITIVE",
              "percentage": "5",
              "applied_money": {
                "amount": 228,
                "currency": "USD"
              }
            },
            {
              "name": "Sales Tax",
              "type": "ADDITIVE",
              "percentage": "8.5",
              "applied_money": {
                "amount": 387,
                "currency": "USD"
              }
            }
          ],
          "discounts": [
            {
              "name": "Father's day 12% OFF",
              "type": "FIXED_PERCENTAGE",
              "percentage": "12",
              "applied_money": {
                "amount": 1260,
                "currency": "USD"
              },
              "scope": "ORDER"
            },
            {
              "name": "$11 off Customer Discount",
              "type": "FIXED_AMOUNT",
              "amount_money": {
                "amount": 1100,
                "currency": "USD"
              },
              "applied_money": {
                "amount": 1100,
                "currency": "USD"
              },
              "scope": "LINE_ITEM"
            },
            {
              "name": "Global Sales $55 OFF",
              "type": "FIXED_AMOUNT",
              "amount_money": {
                "amount": 5500,
                "currency": "USD"
              },
              "applied_money": {
                "amount": 3583,
                "currency": "USD"
              },
              "scope": "ORDER"
            }
          ],
          "base_price_money": {
            "amount": 3500,
            "currency": "USD"
          },
          "total_tax_money": {
            "amount": 615,
            "currency": "USD"
          },
          "total_discount_money": {
            "amount": 5943,
            "currency": "USD"
          },
          "total_money": {
            "amount": 5172,
            "currency": "USD"
          }
        }
      ],
      "total_money": {
        "amount": 7818,
        "currency": "USD"
      },
      "total_tax_money": {
        "amount": 823,
        "currency": "USD"
      },
      "total_discount_money": {
        "amount": 9005,
        "currency": "USD"
      }
    },
    "created_at": "2017-06-16T22:25:35Z",
    "additional_recipients": [
      {
        "location_id": "057P5VYJ4A5X1",
        "description": "Application fees",
        "amount_money": {
          "amount": 60,
          "currency": "USD"
        }
      }
    ]
  }
}

CreateCustomer

POST /v2/customers

Creates a new customer for a business, which can have associated cards on file.

You must provide at least one of the following values in your request to this endpoint:

  • given_name
  • family_name
  • company_name
  • email_address
  • phone_number

Required permissions: CUSTOMERS_WRITE

Body Parameters

Name Type Description
idempotency_key string

The idempotency key for the request. See the Idempotency guide for more information.

given_name string

The customer's given (i.e., first) name.

family_name string

The customer's family (i.e., last) name.

company_name string

The name of the customer's company.

nickname string

A nickname for the customer.

email_address string

The customer's email address.

address Address

The customer's physical address.

phone_number string

The customer's phone number.

reference_id string

An optional second ID you can set to associate the customer with an entity in another system.

note string

An optional note to associate with the customer.

birthday string

The customer birthday in RFC-3339 format. Year is optional, timezone and times are not allowed. Example: 0000-09-01T00:00:00-00:00 for a birthday on September 1st. 1998-09-01T00:00:00-00:00 for a birthday on September 1st 1998.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

customer Customer

The created customer.

Example Request

POST /v2/customers

{
  "given_name": "Amelia",
  "family_name": "Earhart",
  "email_address": "[email protected]",
  "address": {
    "address_line_1": "500 Electric Ave",
    "address_line_2": "Suite 600",
    "locality": "New York",
    "administrative_district_level_1": "NY",
    "postal_code": "10003",
    "country": "US"
  },
  "phone_number": "1-212-555-4240",
  "reference_id": "YOUR_REFERENCE_ID",
  "note": "a customer"
}

Example Response

{
  "customer": {
    "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
    "created_at": "2016-03-23T20:21:54.859Z",
    "updated_at": "2016-03-23T20:21:54.859Z",
    "given_name": "Amelia",
    "family_name": "Earhart",
    "email_address": "[email protected]",
    "address": {
      "address_line_1": "500 Electric Ave",
      "address_line_2": "Suite 600",
      "locality": "New York",
      "administrative_district_level_1": "NY",
      "postal_code": "10003",
      "country": "US"
    },
    "phone_number": "1-212-555-4240",
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "a customer"
  }
}

CreateCustomerCard

POST /v2/customers/{customer_id}/cards

Adds a card on file to an existing customer.

As with charges, calls to CreateCustomerCard are idempotent. Multiple calls with the same card nonce return the same card record that was created with the provided nonce during the first call.

Cards on file are automatically updated on a monthly basis to confirm they are still valid and can be charged.

Required permissions: CUSTOMERS_WRITE

Path Parameters

Name Type Description
customer_id
(required)
string

The ID of the customer to link the card on file to.

Body Parameters

Name Type Description
card_nonce
(required)
string

A card nonce representing the credit card to link to the customer.

Card nonces are generated by the SqPaymentForm that buyers enter their card information into. See Embedding the payment form for more information.

Note: Card nonces generated by digital wallets (e.g., Apple Pay) cannot be used to create a customer card.

billing_address Address

Address information for the card on file. Only the postal_code field is required for payments in the US and Canada.

cardholder_name string

The cardholder's name.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

card Card

The created card on file.

Example Request

POST /v2/customers/{customer_id}/cards

{
  "card_nonce": "YOUR_CARD_NONCE",
  "billing_address": {
    "address_line_1": "500 Electric Ave",
    "address_line_2": "Suite 600",
    "locality": "New York",
    "administrative_district_level_1": "NY",
    "postal_code": "10003",
    "country": "US"
  },
  "cardholder_name": "Amelia Earhart"
}

Example Response

{
  "card": {
    "id": "icard-card_id",
    "card_brand": "VISA",
    "last_4": "1111",
    "exp_month": 11,
    "exp_year": 2018,
    "cardholder_name": "Amelia Earhart",
    "billing_address": {
      "address_line_1": "500 Electric Ave",
      "address_line_2": "Suite 600",
      "locality": "New York",
      "administrative_district_level_1": "NY",
      "postal_code": "10003",
      "country": "US"
    }
  }
}

DeleteCustomer

DELETE /v2/customers/{customer_id}

Deletes a customer from a business, along with any linked cards on file. When two profiles are merged into a single profile, that profile is assigned a new customer_id. You must use the new customer_id to delete merged profiles.

Required permissions: CUSTOMERS_WRITE

Path Parameters

Name Type Description
customer_id
(required)
string

The ID of the customer to delete.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

Example Request

DELETE /v2/customers/{customer_id}

DeleteCustomerCard

DELETE /v2/customers/{customer_id}/cards/{card_id}

Removes a card on file from a customer.

Required permissions: CUSTOMERS_WRITE

Path Parameters

Name Type Description
customer_id
(required)
string

The ID of the customer that the card on file belongs to.

card_id
(required)
string

The ID of the card on file to delete.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

Example Request

DELETE /v2/customers/{customer_id}/cards/{card_id}

ListCustomers

GET /v2/customers

Lists a business's customers.

Required permissions: CUSTOMERS_READ

Query Parameters

Name Type Description
cursor string

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query.

See Pagination for more information.

sort_field string

Indicates how Customers should be sorted. Default: DEFAULT.

sort_order string

Indicates whether Customers should be sorted in ascending (ASC) or descending (DESC) order. Default: ASC.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

customers Customer[]

An array of Customer objects that match your query.

cursor string

A pagination cursor to retrieve the next set of results for your original query to the endpoint. This value is present only if the request succeeded and additional results are available.

See Pagination for more information.

Example Request

GET /v2/customers

Example Response

{
  "customers": [
    {
      "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
      "created_at": "2016-03-23T20:21:54.859Z",
      "updated_at": "2016-03-23T20:21:55Z",
      "given_name": "Amelia",
      "family_name": "Earhart",
      "email_address": "[email protected]",
      "address": {
        "address_line_1": "500 Electric Ave",
        "address_line_2": "Suite 600",
        "locality": "New York",
        "administrative_district_level_1": "NY",
        "postal_code": "10003",
        "country": "US"
      },
      "phone_number": "1-212-555-4240",
      "reference_id": "YOUR_REFERENCE_ID",
      "note": "a customer",
      "groups": [
        {
          "id": "16894e93-96eb-4ced-b24b-f71d42bf084c",
          "name": "Aviation Enthusiasts"
        }
      ]
    }
  ]
}

RetrieveCustomer

GET /v2/customers/{customer_id}

Returns details for a single customer.

Required permissions: CUSTOMERS_READ

Path Parameters

Name Type Description
customer_id
(required)
string

The ID of the customer to retrieve.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

customer Customer

The requested customer.

Example Request

GET /v2/customers/{customer_id}

Example Response

{
  "customer": {
    "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
    "created_at": "2016-03-23T20:21:54.859Z",
    "updated_at": "2016-03-23T20:21:54.859Z",
    "given_name": "Amelia",
    "family_name": "Earhart",
    "email_address": "[email protected]",
    "address": {
      "address_line_1": "500 Electric Ave",
      "address_line_2": "Suite 600",
      "locality": "New York",
      "administrative_district_level_1": "NY",
      "postal_code": "10003",
      "country": "US"
    },
    "phone_number": "1-212-555-4240",
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "a customer",
    "groups": [
      {
        "id": "16894e93-96eb-4ced-b24b-f71d42bf084c",
        "name": "Aviation Enthusiasts"
      }
    ]
  }
}

SearchCustomers

POST /v2/customers/search

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

Required permissions: CUSTOMERS_READ

Body Parameters

Name Type Description
cursor string

Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query.

See Pagination for more information.

limit integer

A limit on the number of results to be returned in a single page. The limit is advisory - the implementation may return more or fewer results. If the supplied limit is negative, zero, or is higher than the maximum limit of 1,000, it will be ignored.

query CustomerQuery

Query customers based on the given conditions and sort order. Calling SearchCustomers without an explicit query parameter will return all customers ordered alphabetically based on given_name and family_name.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

customers Customer[]

An array of Customer objects that match a query.

cursor string

A pagination cursor that can be used during subsequent calls to SearchCustomers to retrieve the next set of results associated with the original query. Pagination cursors are only present when a request succeeds and additional results are available.

See Pagination for more information.

Example Request

POST /v2/customers/search

{
  "query": {
    "filter": {
      "creation_source": {
        "values": [
          "THIRD_PARTY"
        ],
        "rule": "INCLUDE"
      },
      "created_at": {
        "start_at": "2018-01-01T00:00:00-00:00",
        "end_at": "2018-02-01T00:00:00-00:00"
      }
    },
    "sort": {
      "field": "CREATED_AT",
      "order": "ASC"
    }
  },
  "limit": 2
}

Example Response

{
  "customers": [
    {
      "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
      "created_at": "2018-01-23T20:21:54.859Z",
      "updated_at": "2018-04-20T10:02:43.083Z",
      "given_name": "James",
      "family_name": "Bond",
      "email_address": "[email protected]",
      "address": {
        "address_line_1": "505 Electric Ave",
        "address_line_2": "Suite 600",
        "locality": "New York",
        "administrative_district_level_1": "NY",
        "postal_code": "10003",
        "country": "US"
      },
      "phone_number": "1-212-555-4250",
      "reference_id": "YOUR_REFERENCE_ID_2",
      "creation_source": "THIRD_PARTY"
    },
    {
      "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
      "created_at": "2018-01-30T14:10:54.859Z",
      "updated_at": "2018-03-08T18:25:54.859Z",
      "given_name": "Amelia",
      "family_name": "Earhart",
      "email_address": "[email protected]",
      "address": {
        "address_line_1": "500 Electric Ave",
        "address_line_2": "Suite 600",
        "locality": "New York",
        "administrative_district_level_1": "NY",
        "postal_code": "10003",
        "country": "US"
      },
      "phone_number": "1-212-555-4240",
      "reference_id": "YOUR_REFERENCE_ID_1",
      "note": "a customer",
      "creation_source": "THIRD_PARTY"
    }
  ],
  "cursor": "9dpS093Uy12AzeE"
}

UpdateCustomer

PUT /v2/customers/{customer_id}

Updates the details of an existing customer. When two profiles are merged into a single profile, that profile is assigned a new customer_id. You must use the new customer_id to update merged profiles.

You cannot edit a customer's cards on file with this endpoint. To make changes to a card on file, you must delete the existing card on file with the DeleteCustomerCard endpoint, then create a new one with the CreateCustomerCard endpoint.

Required permissions: CUSTOMERS_WRITE

Path Parameters

Name Type Description
customer_id
(required)
string

The ID of the customer to update.

Body Parameters

Name Type Description
given_name string

The customer's given (i.e., first) name.

family_name string

The customer's family (i.e., last) name.

company_name string

The name of the customer's company.

nickname string

A nickname for the customer.

email_address string

The customer's email address.

address Address

The customer's physical address.

phone_number string

The customer's phone number.

reference_id string

An optional second ID you can set to associate the customer with an entity in another system.

note string

An optional note to associate with the customer.

birthday string

The customer birthday in RFC-3339 format. Year is optional, timezone and times are not allowed. Example: 0000-09-01T00:00:00-00:00 for a birthday on September 1st. 1998-09-01T00:00:00-00:00 for a birthday on September 1st 1998.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

customer Customer

The updated customer.

Example Request

PUT /v2/customers/{customer_id}

{
  "phone_number": "",
  "email_address": "[email protected]",
  "note": "updated customer note"
}

Example Response

{
  "customer": {
    "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
    "created_at": "2016-03-23T20:21:54.859Z",
    "updated_at": "2016-03-25T20:21:55Z",
    "given_name": "Amelia",
    "family_name": "Earhart",
    "email_address": "[email protected]",
    "address": {
      "address_line_1": "500 Electric Ave",
      "address_line_2": "Suite 600",
      "locality": "New York",
      "administrative_district_level_1": "NY",
      "postal_code": "10003",
      "country": "US"
    },
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "updated customer note",
    "groups": [
      {
        "id": "16894e93-96eb-4ced-b24b-f71d42bf084c",
        "name": "Aviation Enthusiasts"
      }
    ]
  }
}

ListEmployees

GET /v2/employees

Gets a list of Employee objects for a business.

Required permissions: EMPLOYEES_READ

Query Parameters

Name Type Description
location_id string

Filter employees returned to only those that are associated with the specified location.

status string

Specifies the EmployeeStatus to filter the employee by.

limit integer

The number of employees to be returned on each page.

cursor string

The token required to retrieve the specified page of results.

Response fields

Name Type Description
employees Employee[]

List of employees returned from the request.

cursor string

The token to be used to retrieve the next page of results.

errors Error[]

Any errors that occurred during the request.

Example Request

GET /v2/employees

RetrieveEmployee

GET /v2/employees/{id}

Gets an Employee by Square-assigned employee ID (UUID)

Required permissions: EMPLOYEES_READ

Path Parameters

Name Type Description
id
(required)
string

UUID for the employee that was requested.

Response fields

Name Type Description
employee Employee

The response object.

errors Error[]

Any errors that occurred during the request.

Example Request

GET /v2/employees/{id}

BatchChangeInventory

POST /v2/inventory/batch-change

Applies adjustments and counts to the provided item quantities.

On success: returns the current calculated counts for all objects referenced in the request. On failure: returns a list of related errors.

Required permissions: INVENTORY_WRITE

Body Parameters

Name Type Description
idempotency_key string

A client-supplied, universally unique identifier (UUID) for the request.

See Idempotency in the API Development 101 section for more information.

changes InventoryChange[]

The set of physical counts and inventory adjustments to be made. Changes are applied based on the client-supplied timestamp and may be sent out of order. Max size is 100 changes.

ignore_unchanged_counts boolean

Indicates whether the current physical count should be ignored if the quantity is unchanged since the last physical count. Default: true.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

counts InventoryCount[]

The current counts for all objects referenced in the request.

Example Request

POST /v2/inventory/batch-change

{
  "idempotency_key": "8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe",
  "changes": [
    {
      "type": "PHYSICAL_COUNT",
      "physical_count": {
        "reference_id": "1536bfbf-efed-48bf-b17d-a197141b2a92",
        "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
        "state": "IN_STOCK",
        "location_id": "C6W5YS5QM06F5",
        "quantity": "53",
        "employee_id": "LRK57NSQ5X7PUD05",
        "occurred_at": "2016-11-16T22:25:24.878Z"
      }
    }
  ],
  "ignore_unchanged_counts": true
}

Example Response

{
  "errors": [

  ],
  "counts": [
    {
      "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
      "catalog_object_type": "ITEM_VARIATION",
      "state": "IN_STOCK",
      "location_id": "C6W5YS5QM06F5",
      "quantity": "53",
      "calculated_at": "2016-11-16T22:28:01.223Z"
    }
  ]
}

BatchRetrieveInventoryChanges

POST /v2/inventory/batch-retrieve-changes

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

Results are paginated and sorted in ascending order according their occurred_at timestamp (oldest first).

BatchRetrieveInventoryChanges is a catch-all query endpoint for queries that cannot be handled by other, simpler endpoints.

Required permissions: INVENTORY_READ

Body Parameters

Name Type Description
catalog_object_ids string[]

Filters results by CatalogObject ID. Only applied when set. Default: unset.

location_ids string[]

Filters results by Location ID. Only applied when set. Default: unset.

types string[]

Filters results by InventoryChangeType. Default: [PHYSICAL_COUNT, ADJUSTMENT]. TRANSFER is not supported as a filter. See InventoryChangeType for possible values

states string[]

Filters ADJUSTMENT query results by InventoryState. Only applied when set. Default: unset. See InventoryState for possible values

updated_after string

Provided as an RFC 3339 timestamp. Returns results whose created_at or calculated_at value is after the given time. Default: UNIX epoch (1970-01-01T00:00:00Z).

updated_before string

Provided as an RFC 3339 timestamp. Returns results whose created_at or calculated_at value is strictly before the given time. Default: UNIX epoch (1970-01-01T00:00:00Z).

cursor string

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query.

See Pagination for more information.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

changes InventoryChange[]

The current calculated inventory changes for the requested objects and locations.

cursor string

The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Pagination for more information.

Example Request

POST /v2/inventory/batch-retrieve-changes

{
  "catalog_object_ids": [
    "W62UWFY35CWMYGVWK6TWJDNI"
  ],
  "location_ids": [
    "C6W5YS5QM06F5"
  ],
  "types": [
    "PHYSICAL_COUNT"
  ],
  "states": [
    "IN_STOCK"
  ],
  "updated_after": "2016-11-01T00:00:00.000Z",
  "updated_before": "2016-12-01T00:00:00.000Z"
}

Example Response

{
  "errors": [

  ],
  "changes": [
    {
      "type": "PHYSICAL_COUNT",
      "physical_count": {
        "id": "46YDTW253DWGGK9HMAE6XCAO",
        "reference_id": "22c07cf4-5626-4224-89f9-691112019399",
        "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
        "catalog_object_type": "ITEM_VARIATION",
        "state": "IN_STOCK",
        "location_id": "C6W5YS5QM06F5",
        "quantity": "86",
        "source": {
          "product": "SQUARE_POS",
          "application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0",
          "name": "Square Point of Sale 4.37"
        },
        "employee_id": "LRK57NSQ5X7PUD05",
        "occurred_at": "2016-11-16T22:24:49.028Z",
        "created_at": "2016-11-16T22:25:24.878Z"
      }
    }
  ]
}

BatchRetrieveInventoryCounts

POST /v2/inventory/batch-retrieve-counts

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

Results are paginated and sorted in descending order according to their calculated_at timestamp (newest first).

When updated_after is specified, only counts that have changed since that time (based on the server timestamp for the most recent change) are returned. This allows clients to perform a "sync" operation, for example in response to receiving a Webhook notification.

Required permissions: INVENTORY_READ

Body Parameters

Name Type Description
catalog_object_ids string[]

Filters results by CatalogObject ID. Only applied when set. Default: unset.

location_ids string[]

Filters results by Location ID. Only applied when set. Default: unset.

updated_after string

Provided as an RFC 3339 timestamp. Returns results whose calculated_at value is after the given time. Default: UNIX epoch (1970-01-01T00:00:00Z).

cursor string

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query.

See Pagination for more information.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

counts InventoryCount[]

The current calculated inventory counts for the requested objects and locations.

cursor string

The pagination cursor to be used in a subsequent request. If unset, this is the final response.

See Pagination for more information.

Example Request

POST /v2/inventory/batch-retrieve-counts

{
  "catalog_object_ids": [
    "W62UWFY35CWMYGVWK6TWJDNI"
  ],
  "location_ids": [
    "59TNP9SA8VGDA"
  ],
  "updated_after": "2016-11-16T00:00:00.000Z"
}

Example Response

{
  "errors": [

  ],
  "counts": [
    {
      "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
      "catalog_object_type": "ITEM_VARIATION",
      "state": "IN_STOCK",
      "location_id": "59TNP9SA8VGDA",
      "quantity": "79",
      "calculated_at": "2016-11-16T22:28:01.223Z"
    }
  ]
}

RetrieveInventoryAdjustment

GET /v2/inventory/adjustment/{adjustment_id}

Returns the InventoryAdjustment object with the provided adjustment_id.

Required permissions: INVENTORY_READ

Path Parameters

Name Type Description
adjustment_id
(required)
string

ID of the InventoryAdjustment to retrieve.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

adjustment InventoryAdjustment

The requested InventoryAdjustment.

Example Request

GET /v2/inventory/adjustment/{adjustment_id}

Example Response

{
  "errors": [

  ],
  "adjustment": {
    "id": "UDMOEO78BG6GYWA2XDRYX3KB",
    "reference_id": "4a366069-4096-47a2-99a5-0084ac879509",
    "from_state": "IN_STOCK",
    "to_state": "SOLD",
    "location_id": "C6W5YS5QM06F5",
    "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
    "catalog_object_type": "ITEM_VARIATION",
    "quantity": "7",
    "total_price_money": {
      "amount": 4550,
      "currency": "USD"
    },
    "occurred_at": "2016-11-16T25:44:22.837Z",
    "created_at": "2016-11-17T13:02:15.142Z",
    "source": {
      "product": "SQUARE_POS",
      "application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0",
      "name": "Square Point of Sale 4.37"
    },
    "employee_id": "LRK57NSQ5X7PUD05"
  }
}

RetrieveInventoryChanges

GET /v2/inventory/{catalog_object_id}/changes

Returns a set of physical counts and inventory adjustments for the provided CatalogObject at the requested Locations.

Results are paginated and sorted in descending order according to their occurred_at timestamp (newest first).

There are no limits on how far back the caller can page. This endpoint is useful when displaying recent changes for a specific item. For more sophisticated queries, use a batch endpoint.

Required permissions: INVENTORY_READ

Path Parameters

Name Type Description
catalog_object_id
(required)
string

ID of the CatalogObject to retrieve.

Query Parameters

Name Type Description
location_ids string

The Location IDs to look up as a comma-separated list. An empty list queries all locations.

cursor string

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query.

See Pagination for more information.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

changes InventoryChange[]

The set of inventory changes for the requested object and locations.

cursor string

The pagination cursor to be used in a subsequent request. If unset, this is the final response.

See Pagination for more information.

Example Request

GET /v2/inventory/{catalog_object_id}/changes?location_ids=&cursor=

Example Response

{
  "errors": [

  ],
  "changes": [
    {
      "type": "ADJUSTMENT",
      "adjustment": {
        "id": "OJKJIUANKLMLQANZADNPLKAD",
        "reference_id": "d8207693-168f-4b44-a2fd-a7ff533ddd26",
        "from_state": "IN_STOCK",
        "to_state": "SOLD",
        "location_id": "C6W5YS5QM06F5",
        "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
        "catalog_object_type": "ITEM_VARIATION",
        "quantity": "3",
        "total_price_money": {
          "amount": 5000,
          "currency": "USD"
        },
        "occurred_at": "2016-11-16T22:25:24.878Z",
        "created_at": "2016-11-16T22:25:24.878Z",
        "source": {
          "product": "SQUARE_POS",
          "application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0",
          "name": "Square Point of Sale 4.37"
        },
        "employee_id": "AV7YRCGI2H1J5NQ8E1XIZCNA",
        "transaction_id": "5APV6JYK1SNCZD11AND2RX1Z"
      }
    }
  ]
}

RetrieveInventoryCount

GET /v2/inventory/{catalog_object_id}

Retrieves the current calculated stock count for a given CatalogObject at a given set of Locations. Responses are paginated and unsorted. For more sophisticated queries, use a batch endpoint.

Required permissions: INVENTORY_READ

Path Parameters

Name Type Description
catalog_object_id
(required)
string

ID of the CatalogObject to retrieve.

Query Parameters

Name Type Description
location_ids string

The Location IDs to look up as a comma-separated list. An empty list queries all locations.

cursor string

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query.

See Pagination for more information.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

counts InventoryCount[]

The current calculated inventory counts for the requested object and locations.

cursor string

The pagination cursor to be used in a subsequent request. If unset, this is the final response.

See Pagination for more information.

Example Request

GET /v2/inventory/{catalog_object_id}?location_ids=C6W5YS5QM06F5&cursor=

Example Response

{
  "errors": [

  ],
  "counts": [
    {
      "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
      "catalog_object_type": "ITEM_VARIATION",
      "state": "IN_STOCK",
      "location_id": "C6W5YS5QM06F5",
      "quantity": "22",
      "calculated_at": "2016-11-16T22:28:01.223Z"
    }
  ]
}

RetrieveInventoryPhysicalCount

GET /v2/inventory/physical-count/{physical_count_id}

Returns the InventoryPhysicalCount object with the provided physical_count_id.

Required permissions: INVENTORY_READ

Path Parameters

Name Type Description
physical_count_id
(required)
string

ID of the InventoryPhysicalCount to retrieve.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

count InventoryPhysicalCount

The requested InventoryPhysicalCount.

Example Request

GET /v2/inventory/physical-count/{physical_count_id}

Example Response

{
  "errors": [

  ],
  "count": {
    "id": "ANZADNPLKADOJKJIUANKLMLQ",
    "reference_id": "f857ec37-f9a0-4458-8e23-5b5e0bea4e53",
    "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
    "catalog_object_type": "ITEM_VARIATION",
    "state": "IN_STOCK",
    "location_id": "C6W5YS5QM06F5",
    "quantity": "15",
    "source": {
      "product": "SQUARE_POS",
      "application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0",
      "name": "Square Point of Sale 4.37"
    },
    "employee_id": "LRK57NSQ5X7PUD05",
    "occurred_at": "2016-11-16T22:25:24.878Z",
    "created_at": "2016-11-16T22:25:24.878Z"
  }
}

CreateBreakType

POST /v2/labor/break-types

Creates a new BreakType.

A BreakType is a template for creating Break objects. You must provide the following values in your request to this endpoint:

  • location_id
  • break_name
  • expected_duration
  • is_paid

You can only have 3 BreakType instances per location. If you attempt to add a 4th BreakType for a location, an INVALID_REQUEST_ERROR "Exceeded limit of 3 breaks per location." is returned.

Required permissions: TIMECARDS_SETTINGS_WRITE

Body Parameters

Name Type Description
idempotency_key string

Unique string value to insure idempotency of the operation

break_type
(required)
BreakType

The BreakType to be created.

Response fields

Name Type Description
break_type BreakType

The BreakType that was created by the request.

errors Error[]

Any errors that occurred during the request.

Example Request

POST /v2/labor/break-types

{
  "idempotency_key": "PAD3NG5KSN2GL",
  "break_type": {
    "location_id": "CGJN03P1D08GF",
    "break_name": "Lunch Break",
    "expected_duration": "PT30M",
    "is_paid": true
  }
}

Example Response

{
  "break_type": {
    "id": "49SSVDJG76WF3",
    "location_id": "CGJN03P1D08GF",
    "break_name": "Lunch Break",
    "expected_duration": "PT30M",
    "is_paid": true,
    "version": 1,
    "created_at": "2019-02-26T22:42:54Z",
    "updated_at": "2019-02-26T22:42:54Z"
  }
}

CreateShift

POST /v2/labor/shifts

Creates a new Shift.

A Shift represents a complete work day for a single employee. You must provide the following values in your request to this endpoint:

  • location_id
  • employee_id
  • start_at

An attempt to create a new Shift can result in a BAD_REQUEST error when:

  • The status of the new Shift is OPEN and the employee has another shift with an OPEN status.
  • The start_at date is in the future
  • the start_at or end_at overlaps another shift for the same employee
  • If Breaks are set in the request, a break start_at must not be before the Shift.start_at. A break end_at must not be after the Shift.end_at

Required permissions: TIMECARDS_WRITE

Body Parameters

Name Type Description
idempotency_key string

Unique string value to insure the idempotency of the operation.

shift
(required)
Shift

The Shift to be created

Response fields

Name Type Description
shift Shift

The Shift that was created on the request.

errors Error[]

Any errors that occurred during the request.

Example Request

POST /v2/labor/shifts

{
  "idempotency_key": "HIDSNG5KS478L",
  "shift": {
    "employee_id": "ormj0jJJZ5OZIzxrZYJI",
    "location_id": "PAA1RJZZKXBFG",
    "start_at": "2019-01-25T03:11:00-05:00",
    "end_at": "2019-01-25T13:11:00-05:00",
    "wage": {
      "title": "Barista",
      "hourly_rate": {
        "amount": 1100,
        "currency": "USD"
      }
    },
    "breaks": [
      {
        "start_at": "2019-01-25T06:11:00-05:00",
        "end_at": "2019-01-25T06:16:00-05:00",
        "break_type_id": "REGS1EQR1TPZ5",
        "name": "Tea Break",
        "expected_duration": "PT5M",
        "is_paid": true
      }
    ]
  }
}

Example Response

{
  "shift": {
    "id": "K0YH4CV5462JB",
    "employee_id": "ormj0jJJZ5OZIzxrZYJI",
    "location_id": "PAA1RJZZKXBFG",
    "timezone": "America/New_York",
    "start_at": "2019-01-25T03:11:00-05:00",
    "end_at": "2019-01-25T13:11:00-05:00",
    "wage": {
      "title": "Barista",
      "hourly_rate": {
        "amount": 1100,
        "currency": "USD"
      }
    },
    "breaks": [
      {
        "id": "X7GAQYVVRRG6P",
        "start_at": "2019-01-25T06:11:00-05:00",
        "end_at": "2019-01-25T06:16:00-05:00",
        "break_type_id": "REGS1EQR1TPZ5",
        "name": "Tea Break",
        "expected_duration": "PT5M",
        "is_paid": true
      }
    ],
    "status": "CLOSED",
    "version": 1,
    "created_at": "2019-02-28T00:39:02Z",
    "updated_at": "2019-02-28T00:39:02Z"
  }
}

DeleteBreakType

DELETE /v2/labor/break-types/{id}

Deletes an existing BreakType.

A BreakType can be deleted even if it is referenced from a Shift.

Required permissions: TIMECARDS_SETTINGS_WRITE

Path Parameters

Name Type Description
id
(required)
string

UUID for the BreakType being deleted.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

Example Request

DELETE /v2/labor/break-types/{id}

DeleteShift

DELETE /v2/labor/shifts/{id}

Deletes a Shift.

Required permissions: TIMECARDS_SETTINGS_WRITE

Path Parameters

Name Type Description
id
(required)
string

UUID for the Shift being deleted.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

Example Request

DELETE /v2/labor/shifts/{id}

GetBreakType

GET /v2/labor/break-types/{id}

Returns a single BreakType specified by id.

Required permissions: TIMECARDS_SETTINGS_READ

Path Parameters

Name Type Description
id
(required)
string

UUID for the BreakType being retrieved.

Response fields

Name Type Description
break_type BreakType

The response object.

errors Error[]

Any errors that occurred during the request.

Example Request

GET /v2/labor/break-types/{id}

Example Response

{
  "break_type": {
    "id": "lA0mj_RSOprNPwMUXdYp",
    "location_id": "059SB0E0WCNWS",
    "break_name": "Lunch Break",
    "expected_duration": "PT30M",
    "is_paid": true,
    "version": 1,
    "created_at": "2019-02-21T17:50:00Z",
    "updated_at": "2019-02-21T17:50:00Z"
  }
}

GetEmployeeWage

GET /v2/labor/employee-wages/{id}

Returns a single EmployeeWage specified by id.

Required permissions: EMPLOYEES_READ

Path Parameters

Name Type Description
id
(required)
string

UUID for the EmployeeWage being retrieved.

Response fields

Name Type Description
employee_wage EmployeeWage

The requested EmployeeWage object.

errors Error[]

Any errors that occurred during the request.

Example Request

GET /v2/labor/employee-wages/{id}

Example Response

{
  "employee_wage": {
    "id": "pXS3qCv7BERPnEGedM4S8mhm",
    "employee_id": "33fJchumvVdJwxV0H6L9",
    "title": "Manager",
    "hourly_rate": {
      "amount": 2000,
      "currency": "USD"
    }
  }
}

GetShift

GET /v2/labor/shifts/{id}

Returns a single Shift specified by id.

Required permissions: TIMECARDS_READ

Path Parameters

Name Type Description
id
(required)
string

UUID for the Shift being retrieved.

Response fields

Name Type Description
shift Shift

The requested Shift.

errors Error[]

Any errors that occurred during the request.

Example Request

GET /v2/labor/shifts/{id}

Example Response

{
  "shift": {
    "id": "T35HMQSN89SV4",
    "employee_id": "D71KRMQof6cXGUW0aAv7",
    "location_id": "PAA1RJZZKXBFG",
    "timezone": "America/New_York",
    "start_at": "2019-02-23T18:00:00-05:00",
    "end_at": "2019-02-23T21:00:00-05:00",
    "wage": {
      "title": "Cashier",
      "hourly_rate": {
        "amount": 1457,
        "currency": "USD"
      }
    },
    "breaks": [
      {
        "id": "M9BBKEPQAQD2T",
        "start_at": "2019-02-23T19:00:00-05:00",
        "end_at": "2019-02-23T20:00:00-05:00",
        "break_type_id": "92EPDRQKJ5088",
        "name": "Lunch Break",
        "expected_duration": "PT1H",
        "is_paid": true
      }
    ],
    "status": "CLOSED",
    "version": 1,
    "created_at": "2019-02-27T00:12:12Z",
    "updated_at": "2019-02-27T00:12:12Z"
  }
}

ListBreakTypes

GET /v2/labor/break-types

Returns a paginated list of BreakType instances for a business.

Required permissions: TIMECARDS_SETTINGS_READ

Query Parameters

Name Type Description
location_id string

Filter Break Types returned to only those that are associated with the specified location.

limit integer

Maximum number of Break Types to return per page. Can range between 1 and 200. The default is the maximum at 200.

cursor string

Pointer to the next page of Break Type results to fetch.

Response fields

Name Type Description
break_types BreakType[]

A page of BreakType results.

cursor string

Value supplied in the subsequent request to fetch the next next page of Break Type results.

errors Error[]

Any errors that occurred during the request.

Example Request

GET /v2/labor/break-types?location_id=PAA1RJZZKXBFG&limit=2&cursor=s4R0Z6ecFTzTC4jz8sUDBQTudX3KE313OT9fCt3VUgsXM4sMgED

Example Response

{
  "break_types": [
    {
      "id": "REGS1EQR1TPZ5",
      "location_id": "PAA1RJZZKXBFG",
      "break_name": "Coffee Break",
      "expected_duration": "PT5M",
      "is_paid": false,
      "version": 1,
      "created_at": "2019-01-22T20:47:37Z",
      "updated_at": "2019-01-22T20:47:37Z"
    },
    {
      "id": "92EPDRQKJ5088",
      "location_id": "PAA1RJZZKXBFG",
      "break_name": "Lunch Break",
      "expected_duration": "PT1H",
      "is_paid": true,
      "version": 3,
      "created_at": "2019-01-25T19:26:30Z",
      "updated_at": "2019-01-25T19:26:30Z"
    }
  ],
  "cursor": "2fofTniCgT0yIPAq26kmk0YyFQJZfbWkh73OOnlTHmTAx13NgED"
}

ListEmployeeWages

GET /v2/labor/employee-wages

Returns a paginated list of EmployeeWage instances for a business.

Required permissions: EMPLOYEES_READ

Query Parameters

Name Type Description
employee_id string

Filter wages returned to only those that are associated with the specified employee.

limit integer

Maximum number of Employee Wages to return per page. Can range between 1 and 200. The default is the maximum at 200.

cursor string

Pointer to the next page of Employee Wage results to fetch.

Response fields

Name Type Description
employee_wages EmployeeWage[]

A page of Employee Wage results.

cursor string

Value supplied in the subsequent request to fetch the next next page of Employee Wage results.

errors Error[]

Any errors that occurred during the request.

Example Request

GET /v2/labor/employee-wages?employee_id=33fJchumvVdJwxV0H6L9&limit=4&cursor=s4R0Z6ecFTzTC4jz8sUDBQTudX3KE313OT9fCt3VUgsXM4sMgED

Example Response

{
  "employee_wages": [
    {
      "id": "pXS3qCv7BERPnEGedM4S8mhm",
      "employee_id": "33fJchumvVdJwxV0H6L9",
      "title": "Manager",
      "hourly_rate": {
        "amount": 3250,
        "currency": "USD"
      }
    },
    {
      "id": "rZduCkzYDUVL3ovh1sQgbue6",
      "employee_id": "33fJchumvVdJwxV0H6L9",
      "title": "Cook",
      "hourly_rate": {
        "amount": 2600,
        "currency": "USD"
      }
    },
    {
      "id": "FxLbs5KpPUHa8wyt5ctjubDX",
      "employee_id": "33fJchumvVdJwxV0H6L9",
      "title": "Barista",
      "hourly_rate": {
        "amount": 1600,
        "currency": "USD"
      }
    },
    {
      "id": "vD1wCgijMDR3cX5TPnu7VXto",
      "employee_id": "33fJchumvVdJwxV0H6L9",
      "title": "Cashier",
      "hourly_rate": {
        "amount": 1700,
        "currency": "USD"
      }
    }
  ],
  "cursor": "2fofTniCgT0yIPAq26kmk0YyFQJZfbWkh73OOnlTHmTAx13NgED"
}

ListWorkweekConfigs

GET /v2/labor/workweek-configs

Returns a list of WorkweekConfig instances for a business.

Required permissions: TIMECARDS_SETTINGS_READ

Query Parameters

Name Type Description
limit integer

Maximum number of Workweek Configs to return per page.

cursor string

Pointer to the next page of Workweek Config results to fetch.

Response fields

Name Type Description
workweek_configs WorkweekConfig[]

A page of Employee Wage results.

cursor string

Value supplied in the subsequent request to fetch the next page of Employee Wage results.

errors Error[]

Any errors that occurred during the request.

Example Request

GET /v2/labor/workweek-configs?limit=1&cursor=s4R0Z6ecFTzTC4jz8sUDBQTudX3KE313OT9fCt3VUgsXM4sMgED

Example Response

{
  "workweek_configs": [
    {
      "id": "FY4VCAQN700GM",
      "start_of_week": "MON",
      "start_of_day_local_time": "10:00",
      "version": 11,
      "created_at": "2016-02-04T00:58:24Z",
      "updated_at": "2019-02-28T01:04:35Z"
    }
  ],
  "cursor": "2fofTniCgT0yIPAq26kmk0YyFQJZfbWkh73OOnlTHmTAx13NgED"
}

SearchShifts

POST /v2/labor/shifts/search

Returns a paginated list of Shift records for a business. The list to be returned can be filtered by:

  • Location IDs and
  • employee IDs and
  • shift status (OPEN, CLOSED) and
  • shift start and
  • shift end and
  • work day details

The list can be sorted by:

  • start_at
  • end_at
  • created_at
  • updated_at

Required permissions: TIMECARDS_READ

Body Parameters

Name Type Description
query ShiftQuery

Query filters.

limit integer

number of resources in a page (200 by default).

cursor string

opaque cursor for fetching the next page.

Response fields

Name Type Description
shifts Shift[]

Shifts

cursor string

Opaque cursor for fetching the next page.

errors Error[]

Any errors that occurred during the request.

Example Request

POST /v2/labor/shifts/search

{
  "query": {
    "filter": {
      "workday": {
        "date_range": {
          "start_date": "2019-01-20",
          "end_date": "2019-02-03"
        },
        "match_shifts_by": "START_AT",
        "default_timezone": "America/Los_Angeles"
      }
    }
  },
  "limit": 100
}

Example Response

{
  "shifts": [
    {
      "id": "X714F3HA6D1PT",
      "employee_id": "ormj0jJJZ5OZIzxrZYJI",
      "location_id": "PAA1RJZZKXBFG",
      "timezone": "America/New_York",
      "start_at": "2019-01-21T03:11:00-05:00",
      "end_at": "2019-01-21T13:11:00-05:00",
      "wage": {
        "title": "Barista",
        "hourly_rate": {
          "amount": 1100,
          "currency": "USD"
        }
      },
      "breaks": [
        {
          "id": "SJW7X6AKEJQ65",
          "start_at": "2019-01-21T06:11:00-05:00",
          "end_at": "2019-01-21T06:11:00-05:00",
          "break_type_id": "REGS1EQR1TPZ5",
          "name": "Tea Break",
          "expected_duration": "PT10M",
          "is_paid": true
        }
      ],
      "status": "CLOSED",
      "version": 6,
      "created_at": "2019-01-24T01:12:03Z",
      "updated_at": "2019-02-07T22:21:08Z"
    },
    {
      "id": "GDHYBZYWK0P2V",
      "employee_id": "33fJchumvVdJwxV0H6L9",
      "location_id": "PAA1RJZZKXBFG",
      "timezone": "America/New_York",
      "start_at": "2019-01-22T12:02:00-05:00",
      "end_at": "2019-01-22T13:02:00-05:00",
      "wage": {
        "title": "Cook",
        "hourly_rate": {
          "amount": 1600,
          "currency": "USD"
        }
      },
      "breaks": [
        {
          "id": "BKS6VR7WR748A",
          "start_at": "2019-01-23T14:30:00-05:00",
          "end_at": "2019-01-23T14:40:00-05:00",
          "break_type_id": "WQX00VR99F53J",
          "name": "Tea Break",
          "expected_duration": "PT10M",
          "is_paid": true
        },
        {
          "id": "BQFEZSHFZSC51",
          "start_at": "2019-01-22T12:30:00-05:00",
          "end_at": "2019-01-22T12:44:00-05:00",
          "break_type_id": "P6Q468ZFRN1AC",
          "name": "Coffee Break",
          "expected_duration": "PT15M",
          "is_paid": false
        }
      ],
      "status": "CLOSED",
      "version": 16,
      "created_at": "2019-01-23T23:32:45Z",
      "updated_at": "2019-01-24T00:56:25Z"
    }
  ]
}

UpdateBreakType

PUT /v2/labor/break-types/{id}

Updates an existing BreakType.

Required permissions: TIMECARDS_SETTINGS_WRITE TIMECARDS_SETTINGS_READ

Path Parameters

Name Type Description
id
(required)
string

UUID for the BreakType being updated.

Body Parameters

Name Type Description
break_type BreakType

The updated BreakType.

Response fields

Name Type Description
break_type BreakType

The response object.

errors Error[]

Any errors that occurred during the request.

Example Request

PUT /v2/labor/break-types/{id}

{
  "break_type": {
    "location_id": "26M7H24AZ9N6R",
    "break_name": "Lunch",
    "expected_duration": "PT50M",
    "is_paid": true,
    "version": 1
  }
}

Example Response

{
  "break_type": {
    "id": "Q6JSJS6D4DBCH",
    "location_id": "26M7H24AZ9N6R",
    "break_name": "Lunch",
    "expected_duration": "PT50M",
    "is_paid": true,
    "version": 2,
    "created_at": "2018-06-12T20:19:12Z",
    "updated_at": "2019-02-26T23:12:59Z"
  }
}

UpdateShift

PUT /v2/labor/shifts/{id}

Updates an existing Shift.

When adding a Break to a Shift, any earlier Breaks in the Shift have the end_at property set to a valid RFC-3339 datetime string.

When closing a Shift, all Break instances in the shift must be complete with end_at set on each Break.

Required permissions: TIMECARDS_WRITE TIMECARDS_READ

Path Parameters

Name Type Description
id
(required)
string

ID of the object being updated.

Body Parameters

Name Type Description
shift
(required)
Shift

The updated Shift object.

Response fields

Name Type Description
shift Shift

The updated Shift.

errors Error[]

Any errors that occurred during the request.

Example Request

PUT /v2/labor/shifts/{id}

{
  "shift": {
    "employee_id": "ormj0jJJZ5OZIzxrZYJI",
    "location_id": "PAA1RJZZKXBFG",
    "start_at": "2019-01-25T03:11:00-05:00",
    "end_at": "2019-01-25T13:11:00-05:00",
    "wage": {
      "title": "Bartender",
      "hourly_rate": {
        "amount": 1500,
        "currency": "USD"
      }
    },
    "breaks": [
      {
        "id": "X7GAQYVVRRG6P",
        "start_at": "2019-01-25T06:11:00-05:00",
        "end_at": "2019-01-25T06:16:00-05:00",
        "break_type_id": "REGS1EQR1TPZ5",
        "name": "Tea Break",
        "expected_duration": "PT5M",
        "is_paid": true
      }
    ],
    "version": 1
  }
}

Example Response

{
  "shift": {
    "id": "K0YH4CV5462JB",
    "employee_id": "ormj0jJJZ5OZIzxrZYJI",
    "location_id": "PAA1RJZZKXBFG",
    "timezone": "America/New_York",
    "start_at": "2019-01-25T03:11:00-05:00",
    "end_at": "2019-01-25T13:11:00-05:00",
    "wage": {
      "title": "Bartender",
      "hourly_rate": {
        "amount": 1500,
        "currency": "USD"
      }
    },
    "breaks": [
      {
        "id": "X7GAQYVVRRG6P",
        "start_at": "2019-01-25T06:11:00-05:00",
        "end_at": "2019-01-25T06:16:00-05:00",
        "break_type_id": "REGS1EQR1TPZ5",
        "name": "Tea Break",
        "expected_duration": "PT5M",
        "is_paid": true
      }
    ],
    "status": "CLOSED",
    "version": 2,
    "created_at": "2019-02-28T00:39:02Z",
    "updated_at": "2019-02-28T00:42:41Z"
  }
}

UpdateWorkweekConfig

PUT /v2/labor/workweek-configs/{id}

Updates a WorkweekConfig.

Required permissions: TIMECARDS_SETTINGS_WRITE TIMECARDS_SETTINGS_READ

Path Parameters

Name Type Description
id
(required)
string

UUID for the WorkweekConfig object being updated.

Body Parameters

Name Type Description
workweek_config WorkweekConfig

The updated WorkweekConfig object.

Response fields

Name Type Description
workweek_config WorkweekConfig

The response object.

errors Error[]

Any errors that occurred during the request.

Example Request

PUT /v2/labor/workweek-configs/{id}

{
  "workweek_config": {
    "start_of_week": "MON",
    "start_of_day_local_time": "10:00",
    "version": 10
  }
}

Example Response

{
  "workweek_config": {
    "id": "FY4VCAQN700GM",
    "start_of_week": "MON",
    "start_of_day_local_time": "10:00",
    "version": 11,
    "created_at": "2016-02-04T00:58:24Z",
    "updated_at": "2019-02-28T01:04:35Z"
  }
}

ListLocations

GET /v2/locations

Provides the details for all of a business's locations.

Most other Connect API endpoints have a required location_id path parameter. The id field of the Location objects returned by this endpoint correspond to that location_id parameter.

Required permissions: MERCHANT_PROFILE_READ

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

locations Location[]

The business's locations.

Example Request

GET /v2/locations

Example Response

{
  "locations": [
    {
      "id": "18YC4JDH91E1H",
      "name": "your location name",
      "address": {
        "address_line_1": "123 Main St",
        "locality": "San Francisco",
        "administrative_district_level_1": "CA",
        "postal_code": "94114",
        "country": "US"
      },
      "timezone": "America/Los_Angeles",
      "capabilities": [
        "CREDIT_CARD_PROCESSING"
      ],
      "status": "ACTIVE",
      "created_at": "2016-09-19T17:33:12Z",
      "merchant_id": "3MYCJG5GVYQ8Q",
      "country": "US",
      "language_code": "en-US",
      "currency": "USD",
      "phone_number": "+1 650-354-7217",
      "business_name": "Pumbaa's business name"
    }
  ]
}

BatchRetrieveOrders

POST /v2/locations/{location_id}/orders/batch-retrieve

Retrieves a set of Orders by their IDs.

If a given Order ID does not exist, the ID is ignored instead of generating an error.

Required permissions: ORDERS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the orders' associated location.

Body Parameters

Name Type Description
order_ids
(required)
string[]

The IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request.

Response fields

Name Type Description
orders Order[]

The requested orders. This will omit any requested orders that do not exist or are not charged.

errors Error[]

Any errors that occurred during the request.

Example Request

POST /v2/locations/{location_id}/orders/batch-retrieve

{
  "order_ids": [
    "CAISEM82RcpmcFBM0TfOyiHV3es",
    "CAISENgvlJ6jLWAzERDzjyHVybY"
  ]
}

Example Response

{
  "orders": [
    {
      "id": "CAISEM82RcpmcFBM0TfOyiHV3es",
      "location_id": "LOCATION_ID",
      "reference_id": "my-order-001",
      "line_items": [
        {
          "id": "945986d1-9586-11e6-ad5a-28cfe92138cf",
          "name": "Awesome product",
          "quantity": "1",
          "base_price_money": {
            "amount": 1599,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1599,
            "currency": "USD"
          }
        },
        {
          "id": "a8f4168c-9586-11e6-bdf0-28cfe92138cf",
          "name": "Another awesome product",
          "quantity": "3",
          "base_price_money": {
            "amount": 2000,
            "currency": "USD"
          },
          "total_money": {
            "amount": 6000,
            "currency": "USD"
          }
        }
      ],
      "total_money": {
        "amount": 7599,
        "currency": "USD"
      }
    }
  ]
}

CreateOrder

POST /v2/locations/{location_id}/orders

Creates an Order that can then be referenced as order_id in a request to the Charge endpoint. Orders specify products for purchase, along with discounts, taxes, and other settings to apply to the purchase.

To associate a created order with a request to the Charge endpoint, provide the order's id in the order_id field of your request.

You cannot modify an order after you create it. If you need to modify an order, instead create a new order with modified details.

To learn more about the Orders API, see the Orders API Overview.

Required permissions: ORDERS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the business location to associate the order with.

Body Parameters

Name Type Description
order Order

The order to create. If this field is set, then the only other top-level field that can be set is the idempotency_key.

idempotency_key string

A value you specify that uniquely identifies this order among orders you've created.

If you're unsure whether a particular order was created successfully, you can reattempt it with the same idempotency key without worrying about creating duplicate orders.

See Idempotency for more information.

reference_id string

Deprecated: Please set the reference_id on the nested order field instead.

An optional ID you can associate with the order for your own purposes (such as to associate the order with an entity ID in your own database).

This value cannot exceed 40 characters.

line_items CreateOrderRequestLineItem[]

Deprecated: Please set the line_items on the nested order field instead.

The line items to associate with this order.

Each line item represents a different product to include in a purchase.

taxes CreateOrderRequestTax[]

Deprecated: Please set the taxes on the nested order field instead.

The taxes to include on the order.

discounts CreateOrderRequestDiscount[]

Deprecated: Please set the discounts on the nested order field instead.

The discounts to include on the order.

Response fields

Name Type Description
order Order

The newly created order.

errors Error[]

Any errors that occurred during the request.

Example Request

POST /v2/locations/{location_id}/orders

{
  "idempotency_key": "8193148c-9586-11e6-99f9-28cfe92138cf",
  "reference_id": "my-order-001",
  "line_items": [
    {
      "name": "New York Strip Steak",
      "quantity": "1",
      "base_price_money": {
        "amount": 1599,
        "currency": "USD"
      }
    },
    {
      "quantity": "2",
      "catalog_object_id": "BEMYCSMIJL46OCDV4KYIKXIB",
      "modifiers": [
        {
          "catalog_object_id": "CHQX7Y4KY6N5KINJKZCFURPZ"
        }
      ],
      "discounts": [
        {
          "name": "Sale - $1.00 off",
          "amount_money": {
            "amount": 100,
            "currency": "USD"
          }
        }
      ]
    }
  ],
  "taxes": [
    {
      "name": "State Sales Tax",
      "percentage": "9"
    }
  ],
  "discounts": [
    {
      "name": "Labor Day Sale",
      "percentage": "5"
    },
    {
      "catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7"
    }
  ]
}

Example Response

{
  "order": {
    "id": "CAISENgvlJ6jLWAzERDzjyHVybY",
    "location_id": "LOCATION_ID",
    "line_items": [
      {
        "name": "New York Strip Steak",
        "quantity": "1",
        "taxes": [
          {
            "name": "State Sales Tax",
            "type": "ADDITIVE",
            "percentage": "9",
            "applied_money": {
              "amount": 136,
              "currency": "USD"
            }
          }
        ],
        "discounts": [
          {
            "catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7",
            "name": "Membership Discount",
            "type": "FIXED_PERCENTAGE",
            "percentage": "0.5",
            "applied_money": {
              "amount": 8,
              "currency": "USD"
            },
            "scope": "ORDER"
          },
          {
            "name": "Labor Day Sale",
            "type": "FIXED_PERCENTAGE",
            "percentage": "5",
            "applied_money": {
              "amount": 79,
              "currency": "USD"
            },
            "scope": "ORDER"
          }
        ],
        "base_price_money": {
          "amount": 1599,
          "currency": "USD"
        },
        "gross_sales_money": {
          "amount": 1599,
          "currency": "USD"
        },
        "total_tax_money": {
          "amount": 136,
          "currency": "USD"
        },
        "total_discount_money": {
          "amount": 87,
          "currency": "USD"
        },
        "total_money": {
          "amount": 1648,
          "currency": "USD"
        }
      },
      {
        "name": "New York Steak",
        "quantity": "2",
        "catalog_object_id": "BEMYCSMIJL46OCDV4KYIKXIB",
        "variation_name": "Larger",
        "modifiers": [
          {
            "catalog_object_id": "CHQX7Y4KY6N5KINJKZCFURPZ",
            "name": "Well",
            "base_price_money": {
              "amount": 50,
              "currency": "USD"
            },
            "total_price_money": {
              "amount": 100,
              "currency": "USD"
            }
          }
        ],
        "taxes": [
          {
            "name": "State Sales Tax",
            "type": "ADDITIVE",
            "percentage": "9",
            "applied_money": {
              "amount": 374,
              "currency": "USD"
            }
          }
        ],
        "discounts": [
          {
            "catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7",
            "name": "Membership Discount",
            "type": "FIXED_PERCENTAGE",
            "percentage": "0.5",
            "applied_money": {
              "amount": 22,
              "currency": "USD"
            },
            "scope": "ORDER"
          },
          {
            "name": "Labor Day Sale",
            "type": "FIXED_PERCENTAGE",
            "percentage": "5",
            "applied_money": {
              "amount": 224,
              "currency": "USD"
            },
            "scope": "ORDER"
          },
          {
            "name": "Sale - $1.00 off",
            "type": "FIXED_AMOUNT",
            "amount_money": {
              "amount": 100,
              "currency": "USD"
            },
            "applied_money": {
              "amount": 100,
              "currency": "USD"
            },
            "scope": "LINE_ITEM"
          }
        ],
        "base_price_money": {
          "amount": 2200,
          "currency": "USD"
        },
        "gross_sales_money": {
          "amount": 4500,
          "currency": "USD"
        },
        "total_tax_money": {
          "amount": 374,
          "currency": "USD"
        },
        "total_discount_money": {
          "amount": 346,
          "currency": "USD"
        },
        "total_money": {
          "amount": 4528,
          "currency": "USD"
        }
      }
    ],
    "total_money": {
      "amount": 6176,
      "currency": "USD"
    },
    "total_tax_money": {
      "amount": 510,
      "currency": "USD"
    },
    "total_discount_money": {
      "amount": 433,
      "currency": "USD"
    }
  }
}

ListAdditionalRecipientReceivableRefunds

GET /v2/locations/{location_id}/additional-recipient-receivable-refunds

Returns a list of refunded transactions (across all possible originating locations) relating to monies credited to the provided location ID by another Square account using the additional_recipients field in a transaction.

Max results per page: 50

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list AdditionalRecipientReceivableRefunds for.

Query Parameters

Name Type Description
begin_time string

The beginning of the requested reporting period, in RFC 3339 format.

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time minus one year.

end_time string

The end of the requested reporting period, in RFC 3339 format.

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time.

sort_order string

The order in which results are listed in the response (ASC for oldest first, DESC for newest first).

Default value: DESC

cursor string

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query.

See Pagination for more information.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

receivable_refunds AdditionalRecipientReceivableRefund[]

An array of AdditionalRecipientReceivableRefunds that match your query.

cursor string

A pagination cursor for retrieving the next set of results, if any remain. Provide this value as the cursor parameter in a subsequent request to this endpoint.

See Pagination for more information.

Example Request

GET /v2/locations/{location_id}/additional-recipient-receivable-refunds?begin_time=2016-01-15T00:00:00Z&end_time=2016-01-31T00:00:00Z

Example Response

{
  "receivable_refunds": [
    {
      "id": "Ge2OT7KA6XAg1GC15qs5S",
      "receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF",
      "refund_id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW",
      "transaction_location_id": "18YC4JDH91E1H",
      "amount_money": {
        "amount": 10,
        "currency": "USD"
      },
      "created_at": "2016-01-20T22:57:56Z"
    }
  ]
}

ListAdditionalRecipientReceivables

GET /v2/locations/{location_id}/additional-recipient-receivables

Returns a list of receivables (across all possible sending locations) representing monies credited to the provided location ID by another Square account using the additional_recipients field in a transaction.

Max results per page: 50

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list AdditionalRecipientReceivables for.

Query Parameters

Name Type Description
begin_time string

The beginning of the requested reporting period, in RFC 3339 format.

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time minus one year.

end_time string

The end of the requested reporting period, in RFC 3339 format.

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time.

sort_order string

The order in which results are listed in the response (ASC for oldest first, DESC for newest first).

Default value: DESC

cursor string

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query.

See Pagination for more information.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

receivables AdditionalRecipientReceivable[]

An array of AdditionalRecipientReceivables that match your query.

cursor string

A pagination cursor for retrieving the next set of results, if any remain. Provide this value as the cursor parameter in a subsequent request to this endpoint.

See Pagination for more information.

Example Request

GET /v2/locations/{location_id}/additional-recipient-receivables?begin_time=2016-01-15T00:00:00Z&end_time=2016-01-31T00:00:00Z

Example Response

{
  "receivables": [
    {
      "id": "ISu5xwxJ5v0CMJTQq7RvqyMF",
      "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
      "transaction_location_id": "18YC4JDH91E1H",
      "amount_money": {
        "amount": 20,
        "currency": "USD"
      },
      "created_at": "2016-01-19T15:12:41Z",
      "refunds": [
        {
          "id": "Ge2OT7KA6XAg1GC15qs5S",
          "receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF",
          "refund_id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW",
          "transaction_location_id": "18YC4JDH91E1H",
          "amount_money": {
            "amount": 10,
            "currency": "USD"
          },
          "created_at": "2016-01-20T22:57:56Z"
        }
      ]
    }
  ]
}

CaptureTransaction

POST /v2/locations/{location_id}/transactions/{transaction_id}/capture

Captures a transaction that was created with the Charge endpoint with a delay_capture value of true.

See Delayed capture transactions for more information.

Required permissions: PAYMENTS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string
transaction_id
(required)
string

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

Example Request

POST /v2/locations/{location_id}/transactions/{transaction_id}/capture

Charge

POST /v2/locations/{location_id}/transactions

Charges a card represented by a card nonce or a customer's card on file.

Your request to this endpoint must include either:

  • A value for the card_nonce parameter (to charge a card nonce generated with the SqPaymentForm)
  • Values for the customer_card_id and customer_id parameters (to charge a customer's card on file)

When this response is returned, the amount of Square's processing fee might not yet be calculated. To obtain the processing fee, wait about ten seconds and call RetrieveTransaction. See the processing_fee_money field of each Tender included in the transaction.

Required permissions: PAYMENTS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to associate the created transaction with.

Body Parameters

Name Type Description
idempotency_key
(required)
string

A value you specify that uniquely identifies this transaction among transactions you've created.

If you're unsure whether a particular transaction succeeded, you can reattempt it with the same idempotency key without worrying about double-charging the buyer.

See Idempotency for more information.

amount_money
(required)
Money

The amount of money to charge.

Note that you specify the amount in the smallest denomination of the applicable currency. For example, US dollar amounts are specified in cents. See Working with monetary amounts for details.

The value of currency must match the currency associated with the business that is charging the card.

card_nonce string

A nonce generated from the SqPaymentForm that represents the card to charge.

The application that provides a nonce to this endpoint must be the same application that generated the nonce with the SqPaymentForm. Otherwise, the nonce is invalid.

Do not provide a value for this field if you provide a value for customer_card_id.

customer_card_id string

The ID of the customer card on file to charge. Do not provide a value for this field if you provide a value for card_nonce.

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

delay_capture boolean

If true, the request will only perform an Auth on the provided card. You can then later perform either a Capture (with the CaptureTransaction endpoint) or a Void (with the VoidTransaction endpoint).

Default value: false

reference_id string

An optional ID you can associate with the transaction for your own purposes (such as to associate the transaction with an entity ID in your own database).

This value cannot exceed 40 characters.

note string

An optional note to associate with the transaction.

This value cannot exceed 60 characters.

customer_id string

The ID of the customer to associate this transaction with. This field is required if you provide a value for customer_card_id, and optional otherwise.

billing_address Address

The buyer's billing address.

shipping_address Address

The buyer's shipping address, if available.

buyer_email_address string

The buyer's email address, if available.

order_id string

The ID of the order to associate with this transaction.

If you provide this value, the amount_money value of your request must exactly match the value of the order's total_money field.

additional_recipients AdditionalRecipient[]

The basic primitive of multi-party transaction. The value is optional. The transaction facilitated by you can be split from here.

If you provide this value, the amount_money value in your additional_recipients must not be more than 90% of the amount_money value in the charge request. The location_id must be the valid location of the app owner merchant.

This field requires the PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission.

This field is currently not supported in sandbox.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

transaction Transaction

The created transaction.

Example Request

POST /v2/locations/{location_id}/transactions

{
  "idempotency_key": "74ae1696-b1e3-4328-af6d-f1e04d947a13",
  "shipping_address": {
    "address_line_1": "123 Main St",
    "locality": "San Francisco",
    "administrative_district_level_1": "CA",
    "postal_code": "94114",
    "country": "US"
  },
  "billing_address": {
    "address_line_1": "500 Electric Ave",
    "address_line_2": "Suite 600",
    "administrative_district_level_1": "NY",
    "locality": "New York",
    "postal_code": "10003",
    "country": "US"
  },
  "amount_money": {
    "amount": 200,
    "currency": "USD"
  },
  "additional_recipients": [
    {
      "location_id": "057P5VYJ4A5X1",
      "description": "Application fees",
      "amount_money": {
        "amount": 20,
        "currency": "USD"
      }
    }
  ],
  "card_nonce": "card_nonce_from_square_123",
  "reference_id": "some optional reference id",
  "note": "some optional note",
  "delay_capture": false
}

Example Response

{
  "transaction": {
    "id": "KnL67ZIwXCPtzOrqj0HrkxMF",
    "location_id": "18YC4JDH91E1H",
    "created_at": "2016-03-10T22:57:56Z",
    "tenders": [
      {
        "id": "MtZRYYdDrYNQbOvV7nbuBvMF",
        "location_id": "18YC4JDH91E1H",
        "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
        "created_at": "2016-03-10T22:57:56Z",
        "note": "some optional note",
        "amount_money": {
          "amount": 200,
          "currency": "USD"
        },
        "additional_recipients": [
          {
            "location_id": "057P5VYJ4A5X1",
            "description": "Application fees",
            "amount_money": {
              "amount": 20,
              "currency": "USD"
            },
            "receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF"
          }
        ],
        "type": "CARD",
        "card_details": {
          "status": "CAPTURED",
          "card": {
            "card_brand": "VISA",
            "last_4": "1111"
          },
          "entry_method": "KEYED"
        }
      }
    ],
    "reference_id": "some optional reference id",
    "product": "EXTERNAL_API"
  }
}

CreateRefund

POST /v2/locations/{location_id}/transactions/{transaction_id}/refund

Initiates a refund for a previously charged tender.

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

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
(required)
string

The ID of the original transaction's associated location.

transaction_id
(required)
string

The ID of the original transaction that includes the tender to refund.

Body Parameters

Name Type Description
idempotency_key
(required)
string

A value you specify that uniquely identifies this refund among refunds you've created for the tender.

If you're unsure whether a particular refund succeeded, you can reattempt it with the same idempotency key without worrying about duplicating the refund.

See Idempotency for more information.

tender_id
(required)
string

The ID of the tender to refund.

A Transaction has one or more tenders (i.e., methods of payment) associated with it, and you refund each tender separately with the Connect API.

reason string

A description of the reason for the refund.

Default value: Refund via API

amount_money
(required)
Money

The amount of money to refund.

Note that you specify the amount in the smallest denomination of the applicable currency. For example, US dollar amounts are specified in cents. See Working with monetary amounts for details.

This amount cannot exceed the amount that was originally charged to the tender that corresponds to tender_id.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

refund Refund

The created refund.

Example Request

POST /v2/locations/{location_id}/transactions/{transaction_id}/refund

{
  "idempotency_key": "86ae1696-b1e3-4328-af6d-f1e04d947ad2",
  "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF",
  "reason": "a reason",
  "amount_money": {
    "amount": 100,
    "currency": "USD"
  }
}

Example Response

{
  "refund": {
    "id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW",
    "location_id": "18YC4JDH91E1H",
    "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
    "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF",
    "created_at": "2016-02-12T00:28:18Z",
    "reason": "some reason",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "additional_recipients": [
      {
        "location_id": "057P5VYJ4A5X1",
        "description": "Application fees",
        "amount_money": {
          "amount": 10,
          "currency": "USD"
        },
        "receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF"
      }
    ],
    "status": "PENDING"
  }
}

ListRefunds

GET /v2/locations/{location_id}/refunds

Lists refunds for one of a business's locations.

In addition to full or partial tender refunds processed through Square APIs, refunds may result from itemized returns or exchanges through Square's Point of Sale applications.

Refunds with a status of PENDING are not currently included in this endpoint's response.

Max results per page: 50

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list refunds for.

Query Parameters

Name Type Description
begin_time string

The beginning of the requested reporting period, in RFC 3339 format.

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time minus one year.

end_time string

The end of the requested reporting period, in RFC 3339 format.

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time.

sort_order string

The order in which results are listed in the response (ASC for oldest first, DESC for newest first).

Default value: DESC

cursor string

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query.

See Pagination for more information.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

refunds Refund[]

An array of refunds that match your query.

cursor string

A pagination cursor for retrieving the next set of results, if any remain. Provide this value as the cursor parameter in a subsequent request to this endpoint.

See Pagination for more information.

Example Request

GET /v2/locations/{location_id}/refunds?begin_time=2016-01-15T00:00:00Z&end_time=2016-01-31T00:00:00Z

Example Response

{
  "refunds": [
    {
      "id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW",
      "location_id": "18YC4JDH91E1H",
      "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
      "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF",
      "created_at": "2016-01-20T00:28:18Z",
      "reason": "some reason",
      "amount_money": {
        "amount": 100,
        "currency": "USD"
      },
      "additional_recipients": [
        {
          "location_id": "057P5VYJ4A5X1",
          "description": "Application fees",
          "amount_money": {
            "amount": 10,
            "currency": "USD"
          }
        }
      ],
      "status": "APPROVED"
    }
  ]
}

ListTransactions

GET /v2/locations/{location_id}/transactions

Lists transactions for a particular location.

Transactions include payment information from sales and exchanges and refund information from returns and exchanges.

Max results per page: 50

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list transactions for.

Query Parameters

Name Type Description
begin_time string

The beginning of the requested reporting period, in RFC 3339 format.

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time minus one year.

end_time string

The end of the requested reporting period, in RFC 3339 format.

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time.

sort_order string

The order in which results are listed in the response (ASC for oldest first, DESC for newest first).

Default value: DESC

cursor string

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query.

See Pagination for more information.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

transactions Transaction[]

An array of transactions that match your query.

cursor string

A pagination cursor for retrieving the next set of results, if any remain. Provide this value as the cursor parameter in a subsequent request to this endpoint.

See Pagination for more information.

Example Request

GET /v2/locations/{location_id}/transactions?begin_time=2016-01-15T00:00:00Z&end_time=2016-01-31T00:00:00Z

Example Response

{
  "transactions": [
    {
      "id": "KnL67ZIwXCPtzOrqj0HrkxMF",
      "location_id": "18YC4JDH91E1H",
      "created_at": "2016-01-20T22:57:56Z",
      "tenders": [
        {
          "id": "MtZRYYdDrYNQbOvV7nbuBvMF",
          "location_id": "18YC4JDH91E1H",
          "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
          "created_at": "2016-01-20T22:57:56Z",
          "note": "some optional note",
          "amount_money": {
            "amount": 5000,
            "currency": "USD"
          },
          "processing_fee_money": {
            "amount": 138,
            "currency": "USD"
          },
          "type": "CARD",
          "card_details": {
            "status": "CAPTURED",
            "card": {
              "card_brand": "VISA",
              "last_4": "1111"
            },
            "entry_method": "KEYED"
          },
          "additional_recipients": [
            {
              "location_id": "057P5VYJ4A5X1",
              "description": "Application fees",
              "amount_money": {
                "amount": 20,
                "currency": "USD"
              }
            }
          ]
        }
      ],
      "refunds": [
        {
          "id": "7a5RcVI0CxbOcJ2wMOkE",
          "location_id": "18YC4JDH91E1H",
          "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
          "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF",
          "created_at": "2016-01-20T22:59:20Z",
          "reason": "some reason why",
          "amount_money": {
            "amount": 5000,
            "currency": "USD"
          },
          "status": "APPROVED",
          "processing_fee_money": {
            "amount": 138,
            "currency": "USD"
          },
          "additional_recipients": [
            {
              "location_id": "057P5VYJ4A5X1",
              "description": "Application fees",
              "amount_money": {
                "amount": 100,
                "currency": "USD"
              }
            }
          ]
        }
      ],
      "reference_id": "some optional reference id",
      "product": "EXTERNAL_API"
    }
  ]
}

RetrieveTransaction

GET /v2/locations/{location_id}/transactions/{transaction_id}

Retrieves details for a single transaction.

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the transaction's associated location.

transaction_id
(required)
string

The ID of the transaction to retrieve.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

transaction Transaction

The requested transaction.

Example Request

GET /v2/locations/{location_id}/transactions/{transaction_id}

Example Response

{
  "transaction": {
    "id": "KnL67ZIwXCPtzOrqj0HrkxMF",
    "location_id": "18YC4JDH91E1H",
    "created_at": "2016-03-10T22:57:56Z",
    "tenders": [
      {
        "id": "MtZRYYdDrYNQbOvV7nbuBvMF",
        "location_id": "18YC4JDH91E1H",
        "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
        "created_at": "2016-03-10T22:57:56Z",
        "note": "some optional note",
        "amount_money": {
          "amount": 5000,
          "currency": "USD"
        },
        "processing_fee_money": {
          "amount": 138,
          "currency": "USD"
        },
        "type": "CARD",
        "card_details": {
          "status": "CAPTURED",
          "card": {
            "card_brand": "VISA",
            "last_4": "1111"
          },
          "entry_method": "KEYED"
        },
        "additional_recipients": [
          {
            "location_id": "057P5VYJ4A5X1",
            "description": "Application fees",
            "amount_money": {
              "amount": 20,
              "currency": "USD"
            }
          }
        ]
      }
    ],
    "reference_id": "some optional reference id",
    "product": "EXTERNAL_API"
  }
}

VoidTransaction

POST /v2/locations/{location_id}/transactions/{transaction_id}/void

Cancels a transaction that was created with the Charge endpoint with a delay_capture value of true.

See Delayed capture transactions for more information.

Required permissions: PAYMENTS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string
transaction_id
(required)
string

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

Example Request

POST /v2/locations/{location_id}/transactions/{transaction_id}/void

Connect v1 APIs

CreateEmployee

POST /v1/me/employees

Use the CreateEmployee endpoint to add an employee to a Square account. Employees created with the Connect API have an initial status of INACTIVE. Inactive employees cannot sign in to Square Point of Sale until they are activated from the Square Dashboard. Employee status cannot be changed with the Connect API.

Required permissions: EMPLOYEES_WRITE

Body Parameters

Name Type Description
id string

The employee's unique ID.

first_name
(required)
string

The employee's first name.

last_name
(required)
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.

status string

CWhether the employee is ACTIVE or INACTIVE. Inactive employees cannot sign in to Square Register.Merchants update this field from the Square Dashboard. See V1EmployeeStatus for possible values

external_id string

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

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.

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

status string

CWhether the employee is ACTIVE or INACTIVE. Inactive employees cannot sign in to Square Register.Merchants update this field from the Square Dashboard. See V1EmployeeStatus for possible values

external_id string

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

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.

Example Request

POST /v1/me/employees

CreateEmployeeRole

POST /v1/me/roles

Creates an employee role you can then assign to employees.

Square accounts can include any number of roles that can be assigned to employees. These roles define the actions and permissions granted to an employee with that 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.

Roles are assigned with the V1UpdateEmployee 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.

Required permissions: EMPLOYEES_WRITE

Body Parameters

Name Type Description
id string

The role's unique ID, Can only be set by Square.

name
(required)
string

The role's merchant-defined name.

permissions
(required)
string[]

The role's permissions. See V1EmployeeRolePermissions for possible values

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 employee entity was created, in ISO 8601 format. Is set by Square when the Role is created.

updated_at string

The time when the employee entity was most recently updated, in ISO 8601 format. Is set by Square when the Role updated.

Response fields

Name Type Description
id string

The role's unique ID, Can only be set by Square.

name string

The role's merchant-defined name.

permissions string[]

The role's permissions. See V1EmployeeRolePermissions for possible values

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 employee entity was created, in ISO 8601 format. Is set by Square when the Role is created.

updated_at string

The time when the employee entity was most recently updated, in ISO 8601 format. Is set by Square when the Role updated.

Example Request

POST /v1/me/roles

CreateTimecard

POST /v1/me/timecards

Creates a timecard for an employee and clocks them in with an API_CREATE event and a clockin_time set to the current time unless the request provides a different value. To import timecards from another system (rather than clocking someone in). Specify the clockin_time and* clockout_time in the request.

Timecards correspond to exactly one shift for a given employee, bounded by the 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. An employee that is currently clocked in cannot be clocked in a second time.

Required permissions: TIMECARDS_WRITE

Body Parameters

Name Type Description
id string

The timecard's unique ID.

employee_id
(required)
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 clock-in time for the timecard, in ISO 8601 format.

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

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

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.

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.

Response 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 clock-in time for the timecard, in ISO 8601 format.

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

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

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.

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.

Example Request

POST /v1/me/timecards

DeleteTimecard

DELETE /v1/me/timecards/{timecard_id}

Deletes a timecard. Timecards can also be deleted through the Square Dashboard. Deleted timecards are still accessible through Connect API endpoints, but cannot be modified. The deleted field of the Timecard object indicates whether the timecard has been deleted.

Note*: By default, deleted timecards appear alongside valid timecards in results returned by the ListTimecards endpoint. To filter deleted timecards, include the deleted query parameter in the list request.

Required permissions: TIMECARDS_WRITE

Path Parameters

Name Type Description
timecard_id
(required)
string

The ID of the timecard to delete.

Response fields

Name Type Description

ListCashDrawerShifts

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.

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

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

Query Parameters

Name Type Description
order string

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

begin_time string

The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time minus 90 days.

end_time string

The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time.

Response fields

Name Type Description
items V1CashDrawerShift[]

ListEmployeeRoles

GET /v1/me/roles

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

Required permissions: EMPLOYEES_READ

Query Parameters

Name Type Description
order string

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

limit integer

The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.

batch_token string

A pagination cursor to retrieve the next set of results for your original query to the endpoint.

Response fields

Name Type Description
items V1EmployeeRole[]

ListEmployees

GET /v1/me/employees

Provides summary information for all of a business's employees.

Required permissions: EMPLOYEES_READ

Query Parameters

Name Type Description
order string

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

begin_updated_at string

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

end_updated_at string

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

begin_created_at string

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

end_created_at string

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

status string

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

external_id string

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

limit integer

The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.

batch_token string

A pagination cursor to retrieve the next set of results for your original query to the endpoint.

Response fields

Name Type Description
items V1Employee[]

Example Request

GET /v1/me/employees

ListTimecardEvents

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
(required)
string

The ID of the timecard to list events for.

Response fields

Name Type Description
items V1TimecardEvent[]

ListTimecards

GET /v1/me/timecards

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

Required permissions: TIMECARDS_READ

Query Parameters

Name Type Description
order string

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

employee_id string

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

begin_clockin_time string

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

end_clockin_time string

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

begin_clockout_time string

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

end_clockout_time string

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

begin_updated_at string

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

end_updated_at string

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

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

The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.

batch_token string

A pagination cursor to retrieve the next set of results for your original query to the endpoint.

Response fields

Name Type Description
items V1Timecard[]

RetrieveCashDrawerShift

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

Path Parameters

Name Type Description
location_id
(required)
string

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

shift_id
(required)
string

The shift's ID.

Response fields

Name Type Description
id string

The shift's unique ID.

event_type string

The shift's current state. See V1CashDrawerShiftEventType for possible values

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

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

starting_cash_money V1Money

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

cash_payment_money V1Money

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

cash_refunds_money V1Money

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

cash_paid_in_money V1Money

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

cash_paid_out_money V1Money

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

expected_cash_money V1Money

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 V1Money

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 Register that was connected to the cash drawer.

events V1CashDrawerEvent[]

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

RetrieveEmployee

GET /v1/me/employees/{employee_id}

Provides the details for a single employee.

Required permissions: EMPLOYEES_READ

Path Parameters

Name Type Description
employee_id
(required)
string

The employee's ID.

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

status string

CWhether the employee is ACTIVE or INACTIVE. Inactive employees cannot sign in to Square Register.Merchants update this field from the Square Dashboard. See V1EmployeeStatus for possible values

external_id string

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

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.

Example Request

GET /v1/me/employees/{employee_id}

RetrieveEmployeeRole

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
(required)
string

The role's ID.

Response fields

Name Type Description
id string

The role's unique ID, Can only be set by Square.

name string

The role's merchant-defined name.

permissions string[]

The role's permissions. See V1EmployeeRolePermissions for possible values

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 employee entity was created, in ISO 8601 format. Is set by Square when the Role is created.

updated_at string

The time when the employee entity was most recently updated, in ISO 8601 format. Is set by Square when the Role updated.

RetrieveTimecard

GET /v1/me/timecards/{timecard_id}

Provides the details for a single timecard.

Required permissions: TIMECARDS_READ

Path Parameters

Name Type Description
timecard_id
(required)
string

The timecard's ID.

Response 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 clock-in time for the timecard, in ISO 8601 format.

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

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

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.

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.

UpdateEmployee

PUT /v1/me/employees/{employee_id}

Required permissions: EMPLOYEES_WRITE

Path Parameters

Name Type Description
employee_id
(required)
string

The ID of the role to modify.

Body Parameters

Name Type Description
id string

The employee's unique ID.

first_name
(required)
string

The employee's first name.

last_name
(required)
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.

status string

CWhether the employee is ACTIVE or INACTIVE. Inactive employees cannot sign in to Square Register.Merchants update this field from the Square Dashboard. See V1EmployeeStatus for possible values

external_id string

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

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.

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

status string

CWhether the employee is ACTIVE or INACTIVE. Inactive employees cannot sign in to Square Register.Merchants update this field from the Square Dashboard. See V1EmployeeStatus for possible values

external_id string

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

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.

Example Request

PUT /v1/me/employees/{employee_id}

UpdateEmployeeRole

PUT /v1/me/roles/{role_id}

Modifies the details of an employee role.

Required permissions: EMPLOYEES_WRITE

Path Parameters

Name Type Description
role_id
(required)
string

The ID of the role to modify.

Body Parameters

Name Type Description
id string

The role's unique ID, Can only be set by Square.

name
(required)
string

The role's merchant-defined name.

permissions
(required)
string[]

The role's permissions. See V1EmployeeRolePermissions for possible values

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 employee entity was created, in ISO 8601 format. Is set by Square when the Role is created.

updated_at string

The time when the employee entity was most recently updated, in ISO 8601 format. Is set by Square when the Role updated.

Response fields

Name Type Description
id string

The role's unique ID, Can only be set by Square.

name string

The role's merchant-defined name.

permissions string[]

The role's permissions. See V1EmployeeRolePermissions for possible values

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 employee entity was created, in ISO 8601 format. Is set by Square when the Role is created.

updated_at string

The time when the employee entity was most recently updated, in ISO 8601 format. Is set by Square when the Role updated.

Example Request

PUT /v1/me/roles/{role_id}

UpdateTimecard

PUT /v1/me/timecards/{timecard_id}

Modifies the details of a timecard with an API_EDIT event for the timecard. Updating an active timecard with a clockout_time clocks the employee out.

Required permissions: TIMECARDS_WRITE

Path Parameters

Name Type Description
timecard_id
(required)
string

TThe ID of the timecard to modify.

Body Parameters

Name Type Description
id string

The timecard's unique ID.

employee_id
(required)
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 clock-in time for the timecard, in ISO 8601 format.

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

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

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.

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.

Response 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 clock-in time for the timecard, in ISO 8601 format.

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

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

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.

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.

Example Request

PUT /v1/me/timecards/{timecard_id}

AdjustInventory

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

Adjusts an item variation's current available inventory.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the item's associated location.

variation_id
(required)
string

The ID of the variation to adjust inventory information for.

Body Parameters

Name Type Description
quantity_delta number

The number to adjust the variation's quantity by.

adjustment_type string

The reason for the inventory adjustment. See V1AdjustInventoryRequestAdjustmentType for possible values

memo string

A note about the inventory adjustment.

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

Example Request

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

ApplyFee

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

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the fee's associated location.

item_id
(required)
string

The ID of the item to add the fee to.

fee_id
(required)
string

The ID of the fee to apply.

Response fields

Name Type Description
id 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 (_).

name string

The item's name.

description string

The item's description.

type string

The item's type. This value is NORMAL for almost all items. See V1ItemType for possible values

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1ItemColor for possible values

abbreviation string

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

visibility string

Indicates whether the item is viewable from the merchant's online store (PUBLIC) or PRIVATE. See V1ItemVisibility for possible values

available_online boolean

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

master_image V1ItemImage

The item's master image, if any.

category V1Category

The category the item belongs to, if any.

variations V1Variation[]

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

modifier_lists V1Variation[]

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

fees V1Fee[]

The fees that apply to the item, if any.

taxable boolean

Deprecated. This field is not used.

category_id string

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

available_for_pickup boolean

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

ApplyModifierList

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
(required)
string

The ID of the item's associated location.

modifier_list_id
(required)
string

The ID of the modifier list to apply.

item_id
(required)
string

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

Response fields

Name Type Description
id 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 (_).

name string

The item's name.

description string

The item's description.

type string

The item's type. This value is NORMAL for almost all items. See V1ItemType for possible values

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1ItemColor for possible values

abbreviation string

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

visibility string

Indicates whether the item is viewable from the merchant's online store (PUBLIC) or PRIVATE. See V1ItemVisibility for possible values

available_online boolean

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

master_image V1ItemImage

The item's master image, if any.

category V1Category

The category the item belongs to, if any.

variations V1Variation[]

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

modifier_lists V1Variation[]

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

fees V1Fee[]

The fees that apply to the item, if any.

taxable boolean

Deprecated. This field is not used.

category_id string

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

available_for_pickup boolean

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

CreateCategory

POST /v1/{location_id}/categories

Creates an item category.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to create an item for.

Body Parameters

Name Type Description
id string

The category's unique ID.

name string

The category's name.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Response fields

Name Type Description
id string

The category's unique ID.

name string

The category's name.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Example Request

POST /v1/{location_id}/categories

CreateDiscount

POST /v1/{location_id}/discounts

Creates a discount.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to create an item for.

Body Parameters

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.

amount_money V1Money

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 string

Indicates whether the discount is a FIXED value or entered at the time of sale. See V1DiscountDiscountType for possible values

pin_required boolean

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

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1DiscountColor for possible values

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

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

amount_money V1Money

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 string

Indicates whether the discount is a FIXED value or entered at the time of sale. See V1DiscountDiscountType for possible values

pin_required boolean

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

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1DiscountColor for possible values

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Example Request

POST /v1/{location_id}/discounts

CreateFee

POST /v1/{location_id}/fees

Creates a fee (tax).

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to create a fee for.

Body Parameters

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 string

Forthcoming See V1FeeCalculationPhase for possible values

adjustment_type string

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

applies_to_custom_amounts boolean

If true, the fee applies to custom amounts entered into Square Register 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 string

Whether the fee is ADDITIVE or INCLUSIVE. See V1FeeInclusionType for possible values

type string

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

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

Forthcoming See V1FeeCalculationPhase for possible values

adjustment_type string

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

applies_to_custom_amounts boolean

If true, the fee applies to custom amounts entered into Square Register 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 string

Whether the fee is ADDITIVE or INCLUSIVE. See V1FeeInclusionType for possible values

type string

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Example Request

POST /v1/{location_id}/fees

CreateItem

POST /v1/{location_id}/items

Creates an item and at least one variation for it. 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 for the account, including those specified by other applications. You can never reuse an entity ID. If you do not 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.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to create an item for.

Body Parameters

Name Type Description
id 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 (_).

name string

The item's name.

description string

The item's description.

type string

The item's type. This value is NORMAL for almost all items. See V1ItemType for possible values

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1ItemColor for possible values

abbreviation string

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

visibility string

Indicates whether the item is viewable from the merchant's online store (PUBLIC) or PRIVATE. See V1ItemVisibility for possible values

available_online boolean

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

master_image V1ItemImage

The item's master image, if any.

category V1Category

The category the item belongs to, if any.

variations V1Variation[]

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

modifier_lists V1Variation[]

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

fees V1Fee[]

The fees that apply to the item, if any.

taxable boolean

Deprecated. This field is not used.

category_id string

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

available_for_pickup boolean

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Response fields

Name Type Description
id 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 (_).

name string

The item's name.

description string

The item's description.

type string

The item's type. This value is NORMAL for almost all items. See V1ItemType for possible values

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1ItemColor for possible values

abbreviation string

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

visibility string

Indicates whether the item is viewable from the merchant's online store (PUBLIC) or PRIVATE. See V1ItemVisibility for possible values

available_online boolean

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

master_image V1ItemImage

The item's master image, if any.

category V1Category

The category the item belongs to, if any.

variations V1Variation[]

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

modifier_lists V1Variation[]

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

fees V1Fee[]

The fees that apply to the item, if any.

taxable boolean

Deprecated. This field is not used.

category_id string

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

available_for_pickup boolean

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Example Request

POST /v1/{location_id}/items

CreateModifierList

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
(required)
string

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

Body Parameters

Name Type Description
id string

The modifier list's unique ID.

name string

The modifier list's name.

selection_type string

Indicates whether MULTIPLE options or a SINGLE option from the modifier list can be applied to a single item. See V1ModifierListSelectionType for possible values

modifier_options V1ModifierOption[]

The options included in the modifier list.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Response fields

Name Type Description
id string

The modifier list's unique ID.

name string

The modifier list's name.

selection_type string

Indicates whether MULTIPLE options or a SINGLE option from the modifier list can be applied to a single item. See V1ModifierListSelectionType for possible values

modifier_options V1ModifierOption[]

The options included in the modifier list.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Example Request

POST /v1/{location_id}/modifier-lists

CreateModifierOption

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
(required)
string

The ID of the item's associated location.

modifier_list_id
(required)
string

The ID of the modifier list to edit.

Body Parameters

Name Type Description
id string

The modifier option's unique ID.

name string

The modifier option's name.

price_money V1Money

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 integer

Indicates the modifier option's list position when displayed in Square Register 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.

modifier_list_id string

The ID of the modifier list the option belongs to.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Response fields

Name Type Description
id string

The modifier option's unique ID.

name string

The modifier option's name.

price_money V1Money

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 integer

Indicates the modifier option's list position when displayed in Square Register 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.

modifier_list_id string

The ID of the modifier list the option belongs to.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Example Request

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

CreatePage

POST /v1/{location_id}/pages

Creates a Favorites page in Square Register.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to create an item for.

Body Parameters

Name Type Description
id string

The page's unique identifier.

name string

The page's name, if any.

page_index integer

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

cells V1PageCell[]

The cells included on the page.

Response fields

Name Type Description
id string

The page's unique identifier.

name string

The page's name, if any.

page_index integer

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

cells V1PageCell[]

The cells included on the page.

Example Request

POST /v1/{location_id}/pages

CreateVariation

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
location_id
(required)
string

The ID of the item's associated location.

item_id
(required)
string

The item's ID.

Body Parameters

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 integer

Indicates the variation's list position when displayed in Square Register 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

pricing_type string

Indicates whether the item variation's price is fixed or determined at the time of sale. See V1VariationPricingType for possible values

price_money V1Money

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 string

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

inventory_alert_threshold integer

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.

user_data string

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

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

Indicates the variation's list position when displayed in Square Register 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

pricing_type string

Indicates whether the item variation's price is fixed or determined at the time of sale. See V1VariationPricingType for possible values

price_money V1Money

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 string

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

inventory_alert_threshold integer

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.

user_data string

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Example Request

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

DeleteCategory

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

Deletes an existing item category. Note*: DeleteCategory returns nothing on success but Connect SDKs map the empty response to an empty V1DeleteCategoryRequest object as documented below.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the item's associated location.

category_id
(required)
string

The ID of the category to delete.

Response fields

Name Type Description
id string

The category's unique ID.

name string

The category's name.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

DeleteDiscount

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

Deletes an existing discount. Note*: DeleteDiscount returns nothing on success but Connect SDKs map the empty response to an empty V1DeleteDiscountRequest object as documented below.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the item's associated location.

discount_id
(required)
string

The ID of the discount to delete.

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

amount_money V1Money

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 string

Indicates whether the discount is a FIXED value or entered at the time of sale. See V1DiscountDiscountType for possible values

pin_required boolean

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

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1DiscountColor for possible values

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

DeleteFee

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

Deletes an existing fee (tax). Note*: DeleteFee returns nothing on success but Connect SDKs map the empty response to an empty V1DeleteFeeRequest object as documented below.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the fee's associated location.

fee_id
(required)
string

The ID of the fee to delete.

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

Forthcoming See V1FeeCalculationPhase for possible values

adjustment_type string

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

applies_to_custom_amounts boolean

If true, the fee applies to custom amounts entered into Square Register 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 string

Whether the fee is ADDITIVE or INCLUSIVE. See V1FeeInclusionType for possible values

type string

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

DeleteItem

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

Deletes an existing item and all item variations associated with it. Note*: DeleteItem returns nothing on success but Connect SDKs map the empty response to an empty V1DeleteItemRequest object as documented below.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the item's associated location.

item_id
(required)
string

The ID of the item to modify.

Response fields

Name Type Description
id 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 (_).

name string

The item's name.

description string

The item's description.

type string

The item's type. This value is NORMAL for almost all items. See V1ItemType for possible values

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1ItemColor for possible values

abbreviation string

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

visibility string

Indicates whether the item is viewable from the merchant's online store (PUBLIC) or PRIVATE. See V1ItemVisibility for possible values

available_online boolean

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

master_image V1ItemImage

The item's master image, if any.

category V1Category

The category the item belongs to, if any.

variations V1Variation[]

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

modifier_lists V1Variation[]

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

fees V1Fee[]

The fees that apply to the item, if any.

taxable boolean

Deprecated. This field is not used.

category_id string

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

available_for_pickup boolean

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

DeleteModifierList

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

Deletes an existing item modifier list and all modifier options associated with it. Note*: DeleteModifierList returns nothing on success but Connect SDKs map the empty response to an empty V1DeleteModifierListRequest object as documented below.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the item's associated location.

modifier_list_id
(required)
string

The ID of the modifier list to delete.

Response fields

Name Type Description
id string

The modifier list's unique ID.

name string

The modifier list's name.

selection_type string

Indicates whether MULTIPLE options or a SINGLE option from the modifier list can be applied to a single item. See V1ModifierListSelectionType for possible values

modifier_options V1ModifierOption[]

The options included in the modifier list.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

DeleteModifierOption

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

Deletes an existing item modifier option from a modifier list. Note*: DeleteModifierOption returns nothing on success but Connect SDKs map the empty response to an empty V1DeleteModifierOptionRequest object as documented below.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the item's associated location.

modifier_list_id
(required)
string

The ID of the modifier list to delete.

modifier_option_id
(required)
string

The ID of the modifier list to edit.

Response fields

Name Type Description
id string

The modifier option's unique ID.

name string

The modifier option's name.

price_money V1Money

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 integer

Indicates the modifier option's list position when displayed in Square Register 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.

modifier_list_id string

The ID of the modifier list the option belongs to.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

DeletePage

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

Deletes an existing Favorites page and all of its cells. Note*: DeletePage returns nothing on success but Connect SDKs map the empty response to an empty V1DeletePageRequest object as documented below.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the Favorites page's associated location.

page_id
(required)
string

The ID of the page to delete.

Response fields

Name Type Description
id string

The page's unique identifier.

name string

The page's name, if any.

page_index integer

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

cells V1PageCell[]

The cells included on the page.

DeletePageCell

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

Deletes a cell from a Favorites page in Square Register. Note*: DeletePageCell returns nothing on success but Connect SDKs map the empty response to an empty V1DeletePageCellRequest object as documented below.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the Favorites page's associated location.

page_id
(required)
string

The ID of the page to delete.

Query Parameters

Name Type Description
row string

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

column string

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

Response fields

Name Type Description
id string

The page's unique identifier.

name string

The page's name, if any.

page_index integer

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

cells V1PageCell[]

The cells included on the page.

DeleteVariation

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

Deletes an existing item variation from an item. Note*: DeleteVariation returns nothing on success but Connect SDKs map the empty response to an empty V1DeleteVariationRequest object as documented below.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the item's associated location.

item_id
(required)
string

The ID of the item to delete.

variation_id
(required)
string

The ID of the variation to delete.

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

Indicates the variation's list position when displayed in Square Register 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

pricing_type string

Indicates whether the item variation's price is fixed or determined at the time of sale. See V1VariationPricingType for possible values

price_money V1Money

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 string

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

inventory_alert_threshold integer

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.

user_data string

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

ListCategories

GET /v1/{location_id}/categories

Lists all of a location's item categories.

Required permissions: ITEMS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list categories for.

Response fields

Name Type Description
items V1Category[]

ListDiscounts

GET /v1/{location_id}/discounts

Lists all of a location's discounts.

Required permissions: ITEMS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list categories for.

Response fields

Name Type Description
items V1Discount[]

ListFees

GET /v1/{location_id}/fees

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

Required permissions: ITEMS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list fees for.

Response fields

Name Type Description
items V1Fee[]

ListInventory

GET /v1/{location_id}/inventory

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

Required permissions: ITEMS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the item's associated location.

Query Parameters

Name Type Description
limit integer

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

batch_token string

A pagination cursor to retrieve the next set of results for your original query to the endpoint.

Response fields

Name Type Description
items V1InventoryEntry[]

ListItems

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
(required)
string

The ID of the location to list items for.

Query Parameters

Name Type Description
batch_token string

A pagination cursor to retrieve the next set of results for your original query to the endpoint.

Response fields

Name Type Description
items V1Item[]

ListModifierLists

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
(required)
string

The ID of the location to list modifier lists for.

Response fields

Name Type Description
items V1ModifierList[]

ListPages

GET /v1/{location_id}/pages

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

Required permissions: ITEMS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list Favorites pages for.

Response fields

Name Type Description
items V1Page[]

RemoveFee

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

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the fee's associated location.

item_id
(required)
string

The ID of the item to add the fee to.

fee_id
(required)
string

The ID of the fee to apply.

Response fields

Name Type Description
id 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 (_).

name string

The item's name.

description string

The item's description.

type string

The item's type. This value is NORMAL for almost all items. See V1ItemType for possible values

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1ItemColor for possible values

abbreviation string

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

visibility string

Indicates whether the item is viewable from the merchant's online store (PUBLIC) or PRIVATE. See V1ItemVisibility for possible values

available_online boolean

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

master_image V1ItemImage

The item's master image, if any.

category V1Category

The category the item belongs to, if any.

variations V1Variation[]

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

modifier_lists V1Variation[]

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

fees V1Fee[]

The fees that apply to the item, if any.

taxable boolean

Deprecated. This field is not used.

category_id string

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

available_for_pickup boolean

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

RemoveModifierList

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
(required)
string

The ID of the item's associated location.

modifier_list_id
(required)
string

The ID of the modifier list to remove.

item_id
(required)
string

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

Response fields

Name Type Description
id 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 (_).

name string

The item's name.

description string

The item's description.

type string

The item's type. This value is NORMAL for almost all items. See V1ItemType for possible values

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1ItemColor for possible values

abbreviation string

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

visibility string

Indicates whether the item is viewable from the merchant's online store (PUBLIC) or PRIVATE. See V1ItemVisibility for possible values

available_online boolean

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

master_image V1ItemImage

The item's master image, if any.

category V1Category

The category the item belongs to, if any.

variations V1Variation[]

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

modifier_lists V1Variation[]

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

fees V1Fee[]

The fees that apply to the item, if any.

taxable boolean

Deprecated. This field is not used.

category_id string

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

available_for_pickup boolean

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

RetrieveItem

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
(required)
string

The ID of the item's associated location.

item_id
(required)
string

The item's ID.

Response fields

Name Type Description
id 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 (_).

name string

The item's name.

description string

The item's description.

type string

The item's type. This value is NORMAL for almost all items. See V1ItemType for possible values

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1ItemColor for possible values

abbreviation string

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

visibility string

Indicates whether the item is viewable from the merchant's online store (PUBLIC) or PRIVATE. See V1ItemVisibility for possible values

available_online boolean

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

master_image V1ItemImage

The item's master image, if any.

category V1Category

The category the item belongs to, if any.

variations V1Variation[]

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

modifier_lists V1Variation[]

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

fees V1Fee[]

The fees that apply to the item, if any.

taxable boolean

Deprecated. This field is not used.

category_id string

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

available_for_pickup boolean

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

RetrieveModifierList

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
(required)
string

The ID of the item's associated location.

modifier_list_id
(required)
string

The modifier list's ID.

Response fields

Name Type Description
id string

The modifier list's unique ID.

name string

The modifier list's name.

selection_type string

Indicates whether MULTIPLE options or a SINGLE option from the modifier list can be applied to a single item. See V1ModifierListSelectionType for possible values

modifier_options V1ModifierOption[]

The options included in the modifier list.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

UpdateCategory

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

Modifies the details of an existing item category.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the category's associated location.

category_id
(required)
string

The ID of the category to edit.

Body Parameters

Name Type Description
id string

The category's unique ID.

name string

The category's name.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Response fields

Name Type Description
id string

The category's unique ID.

name string

The category's name.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Example Request

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

UpdateDiscount

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
(required)
string

The ID of the category's associated location.

discount_id
(required)
string

The ID of the discount to edit.

Body Parameters

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.

amount_money V1Money

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 string

Indicates whether the discount is a FIXED value or entered at the time of sale. See V1DiscountDiscountType for possible values

pin_required boolean

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

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1DiscountColor for possible values

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

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

amount_money V1Money

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 string

Indicates whether the discount is a FIXED value or entered at the time of sale. See V1DiscountDiscountType for possible values

pin_required boolean

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

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1DiscountColor for possible values

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Example Request

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

UpdateFee

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
(required)
string

The ID of the fee's associated location.

fee_id
(required)
string

The ID of the fee to edit.

Body Parameters

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 string

Forthcoming See V1FeeCalculationPhase for possible values

adjustment_type string

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

applies_to_custom_amounts boolean

If true, the fee applies to custom amounts entered into Square Register 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 string

Whether the fee is ADDITIVE or INCLUSIVE. See V1FeeInclusionType for possible values

type string

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

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

Forthcoming See V1FeeCalculationPhase for possible values

adjustment_type string

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

applies_to_custom_amounts boolean

If true, the fee applies to custom amounts entered into Square Register 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 string

Whether the fee is ADDITIVE or INCLUSIVE. See V1FeeInclusionType for possible values

type string

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Example Request

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

UpdateItem

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

Modifies the core details of an existing item.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the item's associated location.

item_id
(required)
string

The ID of the item to modify.

Body Parameters

Name Type Description
id 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 (_).

name string

The item's name.

description string

The item's description.

type string

The item's type. This value is NORMAL for almost all items. See V1ItemType for possible values

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1ItemColor for possible values

abbreviation string

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

visibility string

Indicates whether the item is viewable from the merchant's online store (PUBLIC) or PRIVATE. See V1ItemVisibility for possible values

available_online boolean

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

master_image V1ItemImage

The item's master image, if any.

category V1Category

The category the item belongs to, if any.

variations V1Variation[]

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

modifier_lists V1Variation[]

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

fees V1Fee[]

The fees that apply to the item, if any.

taxable boolean

Deprecated. This field is not used.

category_id string

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

available_for_pickup boolean

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Response fields

Name Type Description
id 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 (_).

name string

The item's name.

description string

The item's description.

type string

The item's type. This value is NORMAL for almost all items. See V1ItemType for possible values

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1ItemColor for possible values

abbreviation string

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

visibility string

Indicates whether the item is viewable from the merchant's online store (PUBLIC) or PRIVATE. See V1ItemVisibility for possible values

available_online boolean

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

master_image V1ItemImage

The item's master image, if any.

category V1Category

The category the item belongs to, if any.

variations V1Variation[]

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

modifier_lists V1Variation[]

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

fees V1Fee[]

The fees that apply to the item, if any.

taxable boolean

Deprecated. This field is not used.

category_id string

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

available_for_pickup boolean

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Example Request

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

UpdateModifierList

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

Modifies the details of an existing item modifier list.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the item's associated location.

modifier_list_id
(required)
string

The ID of the modifier list to edit.

Body Parameters

Name Type Description
name string

The modifier list's name.

selection_type string

Indicates whether multiple options from the modifier list can be applied to a single item. See V1UpdateModifierListRequestSelectionType for possible values

Response fields

Name Type Description
id string

The modifier list's unique ID.

name string

The modifier list's name.

selection_type string

Indicates whether MULTIPLE options or a SINGLE option from the modifier list can be applied to a single item. See V1ModifierListSelectionType for possible values

modifier_options V1ModifierOption[]

The options included in the modifier list.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Example Request

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

UpdateModifierOption

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
(required)
string

The ID of the item's associated location.

modifier_list_id
(required)
string

The ID of the modifier list to edit.

modifier_option_id
(required)
string

The ID of the modifier list to edit.

Body Parameters

Name Type Description
id string

The modifier option's unique ID.

name string

The modifier option's name.

price_money V1Money

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 integer

Indicates the modifier option's list position when displayed in Square Register 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.

modifier_list_id string

The ID of the modifier list the option belongs to.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Response fields

Name Type Description
id string

The modifier option's unique ID.

name string

The modifier option's name.

price_money V1Money

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 integer

Indicates the modifier option's list position when displayed in Square Register 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.

modifier_list_id string

The ID of the modifier list the option belongs to.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Example Request

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

UpdatePage

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

Modifies the details of a Favorites page in Square Register.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the Favorites page's associated location

page_id
(required)
string

The ID of the page to modify.

Body Parameters

Name Type Description
id string

The page's unique identifier.

name string

The page's name, if any.

page_index integer

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

cells V1PageCell[]

The cells included on the page.

Response fields

Name Type Description
id string

The page's unique identifier.

name string

The page's name, if any.

page_index integer

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

cells V1PageCell[]

The cells included on the page.

Example Request

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

UpdatePageCell

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

Modifies a cell of a Favorites page in Square Register.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the Favorites page's associated location.

page_id
(required)
string

The ID of the page the cell belongs to.

Body Parameters

Name Type Description
page_id string

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

row integer

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

column integer

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

object_type string

The type of entity represented in the cell (ITEM, DISCOUNT, CATEGORY, or PLACEHOLDER). See V1PageCellObjectType for possible values

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 string

For a cell with an object_type of PLACEHOLDER, this value indicates the cell's special behavior. See V1PageCellPlaceholderType for possible values

Response fields

Name Type Description
id string

The page's unique identifier.

name string

The page's name, if any.

page_index integer

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

cells V1PageCell[]

The cells included on the page.

Example Request

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

UpdateVariation

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
(required)
string

The ID of the item's associated location.

item_id
(required)
string

The ID of the item to modify.

variation_id
(required)
string

The ID of the variation to modify.

Body Parameters

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 integer

Indicates the variation's list position when displayed in Square Register 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

pricing_type string

Indicates whether the item variation's price is fixed or determined at the time of sale. See V1VariationPricingType for possible values

price_money V1Money

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 string

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

inventory_alert_threshold integer

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.

user_data string

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

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

Indicates the variation's list position when displayed in Square Register 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

pricing_type string

Indicates whether the item variation's price is fixed or determined at the time of sale. See V1VariationPricingType for possible values

price_money V1Money

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 string

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

inventory_alert_threshold integer

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.

user_data string

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

Example Request

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

UploadItemImage

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

Uploads a JPEG or PNG image and sets it as the master image for an item. If you upload an image for an item that already has a master image, the new image replaces the existing one.

The request body assumes the multipart boundary for the request is set to BOUNDARY in the Content-Type header, for example:

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

Note: some HTTP libraries will set the multipart boundary for you.

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The Square-issued location ID indicating where the item is available.

item_id
(required)
string

The Square-issued ID of the item to modify.

Body Parameters

Name Type Description
image_data
(required)
byte

The binary image data.

Response fields

Name Type Description
id string

The image's unique ID.

url string

The image's publicly accessible URL.

Example Request

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

ListLocations

GET /v1/me/locations

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

Required permissions: MERCHANT_PROFILE_READ

Response fields

Name Type Description
items V1Merchant[]

Example Request

GET /v1/me/locations

RetrieveBusiness

GET /v1/me

Get a business's information.

Required permissions: MERCHANT_PROFILE_READ

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

Indicates whether the merchant account corresponds to a single-location account (LOCATION) or a business account (BUSINESS). This value is almost always LOCATION. See V1MerchantAccountType for possible values

account_capabilities string[]

Capabilities that are enabled for the merchant's Square account. Capabilities that are not listed in this array are not enabled for the account.

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 Address

The address of the merchant's business.

business_phone V1PhoneNumber

The phone number of the merchant's business.

business_type string

The type of business operated by the merchant. See V1MerchantBusinessType for possible values

shipping_address Address

The merchant's shipping address.

location_details V1MerchantLocationDetails

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

market_url string

The URL of the merchant's online store.

CreateRefund

POST /v1/{location_id}/refunds

Issues a refund for a previously processed payment. You must issue a refund within 60 days of the associated payment.

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 the applicable tender id to the V1CreateRefund endpoint. Issuing a full refund for a split tender payment refunds all tenders associated with the payment.

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.

Required permissions: PAYMENTS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the original payment's associated location.

Body Parameters

Name Type Description
payment_id
(required)
string

The ID of the payment to refund. If you are creating a PARTIAL refund for a split tender payment, instead provide the id of the particular tender you want to refund.

type
(required)
string

TThe type of refund (FULL or PARTIAL). See V1CreateRefundRequestType for possible values

reason
(required)
string

The reason for the refund.

refunded_money V1Money

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

request_idempotence_key string

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

Response fields

Name Type Description
type string

The type of refund See V1RefundType for possible values

reason string

The merchant-specified reason for the refund.

refunded_money V1Money

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

refunded_processing_fee_money V1Money

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

refunded_tax_money V1Money

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

refunded_additive_tax_money V1Money

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

refunded_additive_tax V1PaymentTax[]

All of the additive taxes associated with the refund.

refunded_inclusive_tax_money V1Money

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

refunded_inclusive_tax V1PaymentTax[]

All of the inclusive taxes associated with the refund.

refunded_tip_money V1Money

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

refunded_discount_money V1Money

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

refunded_surcharge_money V1Money

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

refunded_surcharges V1PaymentSurcharge[]

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

A Square-issued ID associated with the refund. For single-tender refunds, payment_id is the ID of the original payment ID. For split-tender refunds, payment_id is the ID of the original tender. For exchange-based refunds (is_exchange == true), payment_id is the ID of the original payment ID even if the payment includes other tenders.

merchant_id string
is_exchange boolean

Indicates whether or not the refund is associated with an exchange. If is_exchange is true, the refund reflects the value of goods returned in the exchange not the total money refunded.

Example Request

POST /v1/{location_id}/refunds

ListBankAccounts

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
(required)
string

The ID of the location to list bank accounts for.

Response fields

Name Type Description
items V1BankAccount[]

ListPayments

GET /v1/{location_id}/payments

Provides summary information for all payments taken for a given Square account during a date range. Date ranges cannot exceed 1 year in length. See Date ranges for details of inclusive and exclusive dates.

Note*: Details for payments processed with Square Point of Sale while in offline mode may 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 ListPayments endpoint might list an offline payment chronologically between online payments that were seen in a previous request.

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list payments for. If you specify me, this endpoint returns payments aggregated from all of the business's locations.

Query Parameters

Name Type Description
order string

The order in which payments are listed in the response.

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

limit integer

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

batch_token string

A pagination cursor to retrieve the next set of results for your original query to the endpoint.

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

Response fields

Name Type Description
items V1Payment[]

ListRefunds

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.

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list refunds for.

Query Parameters

Name Type Description
order string

TThe order in which payments are listed in the response.

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

limit integer

The approximate number of refunds to return in a single response. Default: 100. Max: 200. Response may contain more results than the prescribed limit when refunds are made simultaneously to multiple tenders in a payment or when refunds are generated in an exchange to account for the value of returned goods.

batch_token string

A pagination cursor to retrieve the next set of results for your original query to the endpoint.

Response fields

Name Type Description
items V1Refund[]

Example Request

GET /v1/{location_id}/refunds?begin_time=2016-01-15T00:00:00Z&end_time=2016-01-31T00:00:00Z

ListSettlements

GET /v1/{location_id}/settlements

Provides summary information for all deposits and withdrawals initiated by Square to a linked bank account during a date range. Date ranges cannot exceed one year in length.

Note*: the ListSettlements endpoint does not provide entry information.

Required permissions: SETTLEMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list settlements for. If you specify me, this endpoint returns payments aggregated from all of the business's locations.

Query Parameters

Name Type Description
order string

TThe order in which payments are listed in the response.

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

limit integer

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

status string

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

batch_token string

A pagination cursor to retrieve the next set of results for your original query to the endpoint.

Response fields

Name Type Description
items V1Settlement[]

RetrieveBankAccount

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
(required)
string

The ID of the bank account's associated location.

bank_account_id
(required)
string

The bank account's Square-issued ID. You obtain this value from Settlement objects returned.

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

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.

type string

The bank account's type (for example, savings or checking). See V1BankAccountType for possible values

RetrievePayment

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
(required)
string

The ID of the payment's associated location.

payment_id
(required)
string

The Square-issued payment ID. payment_id comes from Payment objects returned by the List Payments endpoint, Settlement objects returned by the List Settlements endpoint, or Refund objects returned by the List Refunds endpoint.

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

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 V1Money

The sum of all inclusive taxes associated with the payment.

additive_tax_money V1Money

The sum of all additive taxes associated with the payment.

tax_money V1Money

The total of all taxes applied to the payment. This is always the sum of inclusive_tax_money and additive_tax_money.

tip_money V1Money

The total of all tips applied to the payment.

discount_money V1Money

The total of all discounts applied to the payment.

total_collected_money V1Money

The total of all discounts applied to the payment.

processing_fee_money V1Money

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

net_total_money V1Money

The amount to be deposited into the merchant's bank account for the payment.

refunded_money V1Money

The total of all refunds applied to the payment.

swedish_rounding_money V1Money

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 V1Money

The total of all sales, including any applicable taxes.

net_sales_money V1Money

The total of all sales, minus any applicable taxes.

inclusive_tax V1PaymentTax[]

All of the inclusive taxes associated with the payment.

additive_tax V1PaymentTax[]

All of the additive taxes associated with the payment.

tender V1Tender[]

All of the tenders associated with the payment.

refunds V1Refund[]

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 if a merchant chooses to refund money to a tender after previously accepting returned goods as part of an exchange.

itemizations V1PaymentItemization[]

The items purchased in the payment.

surcharge_money V1Money

The total of all surcharges applied to the payment.

surcharges V1PaymentSurcharge[]

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.

RetrieveSettlement

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

Provides comprehensive information for a single settlement.

The returned Settlement objects include an entries field that lists the transactions that contribute to the settlement total. Most settlement entries correspond to a payment payout, but settlement entries are also generated for less common events, like refunds, manual adjustments, or chargeback holds.

Square initiates its regular deposits as indicated in the Deposit Options with Square help article. 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 bank account within 3 business days, but in exceptional cases it may take longer.

Required permissions: SETTLEMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the settlements's associated location.

settlement_id
(required)
string

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

Response fields

Name Type Description
id string

The settlement's unique identifier.

status string

The settlement's current status. See V1SettlementStatus for possible values

total_money V1Money

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.

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.

entries V1SettlementEntry[]

The entries included in this settlement.

API Data Types

AdditionalRecipient

Represents an additional recipient (other than the merchant) receiving a portion of this tender.

Fields

Name Type Description
location_id string

The location ID for a recipient (other than the merchant) receiving a portion of this tender.

description string

The description of the additional recipient.

amount_money Money

The amount of money distributed to the recipient.

receivable_id string

The unique ID for this AdditionalRecipientReceivable, assigned by the server.

AdditionalRecipientReceivable

Represents a monetary distribution of part of a Transaction's amount for Transactions which included additional recipients. The location of this receivable is that same as the one specified in the AdditionalRecipient.

Fields

Name Type Description
id string

The additional recipient receivable's unique ID, issued by Square payments servers.

transaction_id string

The ID of the transaction that the additional recipient receivable was applied to.

transaction_location_id string

The ID of the location that created the receivable. This is the location ID on the associated transaction.

amount_money Money

The amount of the receivable. This will always be non-negative.

created_at string

The time when the additional recipient receivable was created, in RFC 3339 format.

refunds AdditionalRecipientReceivableRefund[]

Any refunds of the receivable that have been applied.

AdditionalRecipientReceivableRefund

A refund of an AdditionalRecipientReceivable. This includes the ID of the additional recipient receivable associated to this object, as well as a reference to the Refund that created this receivable refund.

Fields

Name Type Description
id string

The receivable refund's unique ID, issued by Square payments servers.

receivable_id string

The ID of the receivable that the refund was applied to.

refund_id string

The ID of the refund that is associated to this receivable refund.

transaction_location_id string

The ID of the location that created the receivable. This is the location ID on the associated transaction.

amount_money Money

The amount of the refund. This will always be non-negative.

created_at string

The time when the refund was created, in RFC 3339 format.

Address

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

locality string

The city or town of the address.

sublocality string

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

sublocality_2 string

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

sublocality_3 string

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

administrative_district_level_1 string

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

administrative_district_level_2 string

A civil entity within the address's administrative_district_level_1. In the US, 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 string

The address's country, in ISO 3166-1-alpha-2 format. See Country for possible values

first_name string

Optional first name when it's representing recipient.

last_name string

Optional last name when it's representing recipient.

organization string

Optional organization name when it's representing recipient.

Break

A record of an employee's break during a shift.

Fields

Name Type Description
id string

UUID for this object

start_at string

RFC 3339; follows same timezone info as Shift. Precision up to the minute is respected; seconds are truncated.

end_at string

RFC 3339; follows same timezone info as Shift. Precision up to the minute is respected; seconds are truncated. The end_at minute is not counted when the break length is calculated. For example, a break from 00:00 to 00:11 is considered a 10 minute break (midnight to 10 minutes after midnight).

break_type_id string

The BreakType this Break was templated on.

name string

A human-readable name.

expected_duration string

Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of the break.

is_paid boolean

Whether this break counts towards time worked for compensation purposes.

BreakType

A defined break template that sets an expectation for possible Break instances on a Shift.

Fields

Name Type Description
id string

UUID for this object.

location_id string

The ID of the business location this type of break applies to.

break_name string

A human-readable name for this type of break. Will be displayed to employees in Square products.

expected_duration string

Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of this break. Precision below minutes is truncated.

is_paid boolean

Whether this break counts towards time worked for compensation purposes.

version integer

Used for resolving concurrency issues; request will fail if version provided does not match server version at time of request. If a value is not provided, Square's servers execute a "blind" write; potentially overwriting another writer's data.

created_at string

A read-only timestamp in RFC 3339 format.

updated_at string

A read-only timestamp in RFC 3339 format.

Card

Represents the payment details of a card to be used for payments. These details are determined by the card_nonce generated by SqPaymentForm.

Fields

Name Type Description
id string

Unique ID for this card. Generated by Square.

card_brand string

The card's brand (such as VISA). See CardBrand for possible values

last_4 string

The last 4 digits of the card number.

exp_month integer

The expiration month of the associated card as an integer between 1 and 12.

exp_year integer

The four-digit year of the card's expiration date.

cardholder_name string

The name of the cardholder.

billing_address Address

The billing address for this card.

fingerprint string

Not currently set. Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.

CatalogCategory

A category to which an CatalogItem belongs in the Catalog object model.

Fields

Name Type Description
name string

The category's name. Searchable. This field has max length of 255 Unicode code points.

CatalogCategory Example

          {
  "object": {
    "type": "CATEGORY",
    "id": "#Beverages",
    "present_at_all_locations": true,
    "category_data": {
      "name": "Beverages"
    }
  }
}
        

CatalogDiscount

A discount in the Catalog object model.

Fields

Name Type Description
name string

The discount's name. Searchable. This field has max length of 255 Unicode code points.

discount_type string

Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale. See CatalogDiscountType for possible values

percentage string

The percentage of the discount as a string representation of a decimal number, using a . as the decimal separator and without a % sign. A value of 7.5 corresponds to 7.5%. Specify a percentage of 0 if discount_type is VARIABLE_PERCENTAGE.

Do not include this field for amount-based or variable discounts.

amount_money Money

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

Do not include this field for percentage-based or variable discounts.

pin_required boolean

Indicates whether a mobile staff member needs to enter their PIN to apply the discount to a payment in the Square Point of Sale app.

label_color string

The color of the discount's display label in the Square Point of Sale app. This must be a valid hex color code.

CatalogDiscount Example

          {
  "object": {
    "type": "DISCOUNT",
    "id": "#Maythe4th",
    "present_at_all_locations": true,
    "discount_data": {
      "name": "Welcome to the Dark(Roast) Side!",
      "discount_type": "FIXED_PERCENTAGE",
      "percentage": "5.4",
      "pin_required": false,
      "label_color": "red"
    }
  }
}
        

CatalogIdMapping

A mapping between a client-supplied temporary ID and a permanent server ID.

Fields

Name Type Description
client_object_id string

The client-supplied, temporary #-prefixed ID for a new CatalogObject.

object_id string

The permanent ID for the CatalogObject created by the server.

CatalogImage

An image file to use in Square catalogs. Can be associated with catalog items, item variations, and categories.

Fields

Name Type Description
name string

The internal name of this image. Identifies this image in calls to the Connect APIs.

url string

The URL of this image. Generated by Square after an image is uploaded to the CreateCatalogImage endpoint.

caption string

A caption that describes what is shown in the image. Displayed in the Square Online Store.

CatalogInfoResponseLimits

Fields

Name Type Description
batch_upsert_max_objects_per_batch integer

The maximum number of objects that may appear within a single batch in a /v2/catalog/batch-upsert request.

batch_upsert_max_total_objects integer

The maximum number of objects that may appear across all batches in a /v2/catalog/batch-upsert request.

batch_retrieve_max_object_ids integer

The maximum number of object IDs that may appear in a /v2/catalog/batch-retrieve request.

search_max_page_limit integer

The maximum number of results that may be returned in a page of a /v2/catalog/search response.

batch_delete_max_object_ids integer

The maximum number of object IDs that may be included in a single /v2/catalog/batch-delete request.

update_item_taxes_max_item_ids integer

The maximum number of item IDs that may be included in a single /v2/catalog/update-item-taxes request.

update_item_taxes_max_taxes_to_enable integer

The maximum number of tax IDs to be enabled that may be included in a single /v2/catalog/update-item-taxes request.

update_item_taxes_max_taxes_to_disable integer

The maximum number of tax IDs to be disabled that may be included in a single /v2/catalog/update-item-taxes request.

update_item_modifier_lists_max_item_ids integer

The maximum number of item IDs that may be included in a single /v2/catalog/update-item-modifier-lists request.

update_item_modifier_lists_max_modifier_lists_to_enable integer

The maximum number of modifier list IDs to be enabled that may be included in a single /v2/catalog/update-item-modifier-lists request.

update_item_modifier_lists_max_modifier_lists_to_disable integer

The maximum number of modifier list IDs to be disabled that may be included in a single /v2/catalog/update-item-modifier-lists request.

CatalogItem

An item (i.e., product family) in the Catalog object model.

Fields

Name Type Description
name string

The item's name. Searchable. This field must not be empty. This field has max length of 512 Unicode code points.

description string

The item's description. Searchable. This field has max length of 4096 Unicode code points.

abbreviation string

The text of the item's display label in the Square Point of Sale app. Only up to the first five characters of the string are used. Searchable. This field has max length of 24 Unicode code points.

label_color string

The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code.

available_online boolean

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

available_for_pickup boolean

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

available_electronically boolean

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

category_id string

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

tax_ids string[]

A set of IDs indicating the CatalogTaxes that are enabled for this item. When updating an item, any taxes listed here will be added to the item. CatalogTaxes may also be added to or deleted from an item using UpdateItemTaxes.

modifier_list_info CatalogItemModifierListInfo[]

A set of CatalogItemModifierListInfo objects representing the modifier lists that apply to this item, along with the overrides and min and max limits that are specific to this item. CatalogModifierLists may also be added to or deleted from an item using UpdateItemModifierLists.

variations CatalogObject[]

A list of CatalogObjects containing the CatalogItemVariations for this item.

product_type string

The product type of the item. May not be changed once an item has been created.

Only items of product type REGULAR may be created by this API; items with other product types are read-only. See CatalogItemProductType for possible values

skip_modifier_screen boolean

If false, the Square Point of Sale app will present the CatalogItem's details screen immediately, allowing the merchant to choose CatalogModifiers before adding the item to the cart. This is the default behavior.

If true, the Square Point of Sale app will immediately add the item to the cart with the pre-selected modifiers, and merchants can edit modifiers by drilling down onto the item's details.

Third-party clients are encouraged to implement similar behaviors.

CatalogItem Example

          {
  "object": {
    "type": "ITEM",
    "id": "#Cocoa",
    "present_at_all_locations": true,
    "item_data": {
      "name": "Cocoa",
      "description": "Hot chocolate",
      "abbreviation": "Ch",
      "visibility": "PRIVATE"
    }
  }
}
        

CatalogItemModifierListInfo

Controls the properties of a CatalogModifierList as it applies to this CatalogItem.

Fields

Name Type Description
modifier_list_id string

The ID of the CatalogModifierList controlled by this CatalogModifierListInfo.

modifier_overrides CatalogModifierOverride[]

A set of CatalogModifierOverride objects that override whether a given CatalogModifier is enabled by default.

min_selected_modifiers integer

If zero or larger, the smallest number of CatalogModifiers that must be selected from this CatalogModifierList.

max_selected_modifiers integer

If zero or larger, the largest number of CatalogModifiers that can be selected from this CatalogModifierList.

enabled boolean

If true, enable this CatalogModifierList.

CatalogItemVariation

An item variation (i.e., product) in the Catalog object model.

Fields

Name Type Description
item_id string

The ID of the CatalogItem associated with this item variation. Searchable.

name string

The item variation's name. Searchable. This field has max length of 255 Unicode code points.

sku string

The item variation's SKU, if any. Searchable.

upc string

The item variation's UPC, if any. Searchable in the Connect API. This field is only exposed in the Connect API. It is not exposed in Square's Dashboard, Square Point of Sale app or Retail Point of Sale app.

ordinal integer

The order in which this item variation should be displayed. This value is read-only. On writes, the ordinal for each item variation within a parent CatalogItem is set according to the item variations's position. On reads, the value is not guaranteed to be sequential or unique.

pricing_type string

Indicates whether the item variation's price is fixed or determined at the time of sale. See CatalogPricingType for possible values

price_money Money

The item variation's price, if fixed pricing is used.

location_overrides ItemVariationLocationOverrides[]

Per-location price and inventory overrides.

track_inventory boolean

If true, inventory tracking is active for the variation.

inventory_alert_type string

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

inventory_alert_threshold integer

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 user metadata to associate with the item variation. Cannot exceed 255 characters. Searchable.

service_duration integer

If the CatalogItem that owns this item variation is of type APPOINTMENTS_SERVICE, then this is the duration of the service in milliseconds. For example, a 30 minute appointment would have the value 1800000, which is equal to 30 (minutes) * 60 (seconds per minute) * 1000 (milliseconds per second).

CatalogModifier

A modifier in the Catalog object model.

Fields

Name Type Description
name string

The modifier's name. Searchable. This field has max length of 255 Unicode code points.

price_money Money

The modifier's price.

CatalogModifier Example

          {
  "object": {
    "type": "MODIFIER",
    "present_at_all_locations": true,
    "modifier_data": {
      "name": "Almond Milk",
      "price_money": {
        "amount": 250,
        "currency": "USD"
      }
    }
  }
}
        

CatalogModifierList

A modifier list in the Catalog object model. A CatalogModifierList contains Modifiers that can be applied to a CatalogItem at the time of sale.

For example, a modifier list "Condiments" that would apply to a "Hot Dog" CatalogItem might contain CatalogModifiers "Ketchup", "Mustard", and "Relish". The selection_type field specifies whether or not multiple selections from the modifier list are allowed.

Fields

Name Type Description
name string

The CatalogModifierList's name. Searchable. This field has max length of 255 Unicode code points.

selection_type string

Indicates whether multiple options from the CatalogModifierList can be applied to a single CatalogItem. See CatalogModifierListSelectionType for possible values

modifiers CatalogObject[]

The options included in the CatalogModifierList. You must include at least one CatalogModifier. Each CatalogObject must have type MODIFIER and contain CatalogModifier data.

CatalogModifierList Example

          {
  "type": "MODIFIER_LIST",
  "id": "#MilkType",
  "present_at_all_locations": true,
  "modifier_list_data": {
    "name": "Milk Type",
    "selection_type": "SINGLE",
    "modifiers": [
      {
        "type": "MODIFIER",
        "present_at_all_locations": true,
        "modifier_data": {
          "name": "Whole Milk",
          "price_money": {
            "amount": 0,
            "currency": "USD"
          }
        }
      },
      {
        "type": "MODIFIER",
        "present_at_all_locations": true,
        "modifier_data": {
          "name": "Almond Milk",
          "price_money": {
            "amount": 250,
            "currency": "USD"
          }
        }
      },
      {
        "type": "MODIFIER",
        "present_at_all_locations": true,
        "modifier_data": {
          "name": "Soy Milk",
          "price_money": {
            "amount": 250,
            "currency": "USD"
          }
        }
      }
    ]
  }
}
        

CatalogModifierOverride

Fields

Name Type Description
modifier_id string

The ID of the CatalogModifier whose default behavior is being overridden.

on_by_default boolean

If true, this CatalogModifier should be selected by default for this CatalogItem.

CatalogObject

The wrapper object for object types in the Catalog data model. The type of a particular CatalogObject is determined by the value of type and only the corresponding data field may be set.

  • if type = ITEM, only item_data will be populated and it will contain a valid CatalogItem object.
  • if type = ITEM_VARIATION, only item_variation_data will be populated and it will contain a valid CatalogItemVariation object.
  • if type = MODIFIER, only modifier_data will be populated and it will contain a valid CatalogModifier object.
  • if type = MODIFIER_LIST, only modifier_list_data will be populated and it will contain a valid CatalogModifierList object.
  • if type = CATEGORY, only category_data will be populated and it will contain a valid CatalogCategory object.
  • if type = DISCOUNT, only discount_data will be populated and it will contain a valid CatalogDiscount object.
  • if type = TAX, only tax_data will be populated and it will contain a valid CatalogTax object.
  • if type = IMAGE, only image_data will be populated and it will contain a valid CatalogImage object.

For a more detailed discussion of the Catalog data model, please see the Catalog Overview.

Fields

Name Type Description
type string

The type of this object. Each object type has expected properties expressed in a structured format within its corresponding *_data field below. See CatalogObjectType for possible values

id string

An identifier to reference this object in the catalog. When a new CatalogObject is inserted, the client should set the id to a temporary identifier starting with a '#' character. Other objects being inserted or updated within the same request may use this identifier to refer to the new object.

When the server receives the new object, it will supply a unique identifier that replaces the temporary identifier for all future references.

updated_at string

Last modification timestamp in RFC 3339 format, e.g., "2016-08-15T23:59:33.123Z" would indicate the UTC time (denoted by Z) of August 15, 2016 at 23:59:33 and 123 milliseconds.

version integer

The version of the object. When updating an object, the version supplied must match the version in the database, otherwise the write will be rejected as conflicting.

is_deleted boolean

If true, the object has been deleted from the database. Must be false for new objects being inserted. When deleted, the updated_at field will equal the deletion time.

catalog_v1_ids CatalogV1Id[]

The Connect V1 IDs for this object at each location where it is present, where they differ from the object's Connect V2 ID. The field will only be present for objects that have been created or modified by legacy APIs.

present_at_all_locations boolean

If true, this object is present at all locations (including future locations), except where specified in the absent_at_location_ids field. If false, this object is not present at any locations (including future locations), except where specified in the present_at_location_ids field. If not specified, defaults to true.

present_at_location_ids string[]

A list of locations where the object is present, even if present_at_all_locations is false.

absent_at_location_ids string[]

A list of locations where the object is not present, even if present_at_all_locations is true.

image_id string

Identifies the CatalogImage attached to this CatalogObject.

item_data CatalogItem

Structured data for a CatalogItem, set for CatalogObjects of type ITEM.

category_data CatalogCategory

Structured data for a CatalogCategory, set for CatalogObjects of type CATEGORY.

item_variation_data CatalogItemVariation

Structured data for a CatalogItemVariation, set for CatalogObjects of type ITEM_VARIATION.

tax_data CatalogTax

Structured data for a CatalogTax, set for CatalogObjects of type TAX.

discount_data CatalogDiscount

Structured data for a CatalogDiscount, set for CatalogObjects of type DISCOUNT.

modifier_list_data CatalogModifierList

Structured data for a CatalogModifierList, set for CatalogObjects of type MODIFIER_LIST.

modifier_data CatalogModifier

Structured data for a CatalogModifier, set for CatalogObjects of type MODIFIER.

image_data CatalogImage

Structured data for a CatalogImage, set for CatalogObjects of type IMAGE.

CatalogObject Schema

          {
  "catalog_object": {
    "type": "{{ [ITEM | ITEM_VARIATION | MODIFIER | MODIFIER_LIST | CATEGORY | DISCOUNT | TAX] }}",
    "id": "{{ set by Catalog during object creation }}",
    "updated_at": "{{ date & time of most recent update }}",
    "version": "{{ version of the CatalogObject }}",
    "is_deleted": "{{ [true | false] }}",
    "connect_v1_ids": {
      "catalog_v1_id": "{{ itemID from Catalog v1 }}",
      "location_id": "{{ location where v1 ID is used }}"
    },
    "present_at_all_locations": "{{ [true | false] }}",
    "present_at_location_ids": [
      "{{ LOCATIONID-1 }}",
      "{{ LOCATIONID-N }}"
    ],
    "absent_at_location_ids": [
      "{{ LOCATIONID-1 }}",
      "{{ LOCATIONID-N }}"
    ],
    "item_data": "{{ CatalogItem object only if type=ITEM }}",
    "item_variation_data": "{{ CatalogItemVariation object only if type=ITEM_VARIATION }}",
    "modifier_data": "{{ CatalogModifier object only if type=MODIFIER }}",
    "modifier_list_data": "{{ CatalogModifierList object only if type=MODIFIER_LIST }}",
    "category_data": "{{ CatalogCategory object only if type=CATEGORY }}",
    "discount_data": "{{ CatalogDiscount object only if type=DISCOUNT }}",
    "tax_data": "{{ CatalogTax object only if type=TAX }}"
  }
}
        

CatalogObjectBatch

A batch of CatalogObjects.

Fields

Name Type Description
objects CatalogObject[]

A list of CatalogObjects belonging to this batch.

CatalogQuery

A query to be applied to a SearchCatalogObjectsRequest. Only one query field may be present.

Where an attribute name is required, it should be specified as the name of any field marked "searchable" from the structured data types for the desired result object type(s) (CatalogItem, CatalogItemVariation, CatalogCategory, CatalogTax, CatalogDiscount, CatalogModifierList, CatalogModifier).

For example, a query that should return Items may specify attribute names from any of the searchable fields of the CatalogItem data type, namely "name", "description", and "abbreviation".

Fields

Name Type Description
sorted_attribute_query CatalogQuerySortedAttribute

A query that returns all objects, sorted by the given attribute.

exact_query CatalogQueryExact

A query that returns only objects for which the given (string-valued) attribute has the given case-insensitive value.

prefix_query CatalogQueryPrefix

A query that returns only objects for which the given (string-valued) attribute has the given case-insensitive prefix.

range_query CatalogQueryRange

A query that returns only objects for which the given (integer-valued) attribute lies in the given range.

text_query CatalogQueryText

A query that returns only objects whose searchable attributes contain all of the given keywords as prefixes. For example, if a CatalogItem contains attributes {"name": "t-shirt"} and {"description": "Small, Purple"}, it will be matched by the query {"keywords": ["shirt", "sma", "purp"]}.

items_for_tax_query CatalogQueryItemsForTax

A query that returns all CatalogItems that have any of the given CatalogTaxes enabled.

items_for_modifier_list_query CatalogQueryItemsForModifierList

A query that returns all CatalogItems that have any of the given CatalogModifierLists enabled.

CatalogQueryExact

Fields

Name Type Description
attribute_name string

The name of the attribute to be searched.

attribute_value string

The desired value of the search attribute.

CatalogQueryItemsForModifierList

Fields

Name Type Description
modifier_list_ids string[]

A set of CatalogModifierList IDs to be used to find associated CatalogItems.

CatalogQueryItemsForTax

Fields

Name Type Description
tax_ids string[]

A set of CatalogTax IDs to be used to find associated CatalogItems.

CatalogQueryPrefix

Fields

Name Type Description
attribute_name string

The name of the attribute to be searched.

attribute_prefix string

The desired prefix of the search attribute value.

CatalogQueryRange

Fields

Name Type Description
attribute_name string

The name of the attribute to be searched.

attribute_min_value integer

The desired minimum value for the search attribute (inclusive).

attribute_max_value integer

The desired maximum value for the search attribute (inclusive).

CatalogQuerySortedAttribute

Fields

Name Type Description
attribute_name string

The attribute whose value should be used as the sort key.

initial_attribute_value string

The first attribute value to be returned by the query. Ascending sorts will return only objects with this value or greater, while descending sorts will return only objects with this value or less. If unset, start at the beginning (for ascending sorts) or end (for descending sorts).

sort_order string

The desired SortOrder, "ASC" (ascending) or "DESC" (descending). See SortOrder for possible values

CatalogQueryText

Fields

Name Type Description
keywords string[]

A list of one, two, or three search keywords. Keywords with fewer than three characters are ignored.

CatalogTax

A tax in the Catalog object model.

Fields

Name Type Description
name string

The tax's name. Searchable. This field has max length of 255 Unicode code points.

calculation_phase string

Whether the tax is calculated based on a payment's subtotal or total. See TaxCalculationPhase for possible values

inclusion_type string

Whether the tax is ADDITIVE or INCLUSIVE. See TaxInclusionType for possible values

percentage string

The percentage of the tax in decimal form, using a '.' as the decimal separator and without a '%' sign. A value of 7.5 corresponds to 7.5%.

applies_to_custom_amounts boolean

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

enabled boolean

If true, the tax will be shown as enabled in the Square Point of Sale app.

CatalogTax Example

          {
  "object": {
    "type": "TAX",
    "id": "#SalesTax",
    "present_at_all_locations": true,
    "tax_data": {
      "name": "Sales Tax",
      "calculation_phase": "TAX_SUBTOTAL_PHASE",
      "inclusion_type": "ADDITIVE",
      "percentage": "5.0",
      "fee_applies_to_custom_amounts": true,
      "enabled": true
    }
  }
}
        

CatalogV1Id

An Items Connect V1 object ID along with its associated location ID.

Fields

Name Type Description
catalog_v1_id string

The ID for an object in Connect V1, if different from its Connect V2 ID.

location_id string

The ID of the location this Connect V1 ID is associated with.

ChargeRequestAdditionalRecipient

Represents an additional recipient (other than the merchant) entitled to a portion of the tender. Support is currently limited to USD, CAD and GBP currencies

Fields

Name Type Description
location_id string

The location ID for a recipient (other than the merchant) receiving a portion of the tender.

description string

The description of the additional recipient.

amount_money Money

The amount of money distributed to the recipient.

Checkout

Square Checkout lets merchants accept online payments for supported payment types using a checkout workflow hosted on squareup.com.

Fields

Name Type Description
id string

ID generated by Square Checkout when a new checkout is requested.

checkout_page_url string

The URL that the buyer's browser should be redirected to after the checkout is completed.

ask_for_shipping_address boolean

If true, Square Checkout will collect shipping information on your behalf and store that information with the transaction information in your Square Dashboard.

Default: false.

merchant_support_email string

The email address to display on the Square Checkout confirmation page and confirmation email that the buyer can use to contact the merchant.

If this value is not set, the confirmation page and email will display the primary email address associated with the merchant's Square account.

Default: none; only exists if explicitly set.

pre_populate_buyer_email string

If provided, the buyer's email is pre-populated on the checkout page as an editable text field.

Default: none; only exists if explicitly set.

pre_populate_shipping_address Address

If provided, the buyer's shipping info is pre-populated on the checkout page as editable text fields.

Default: none; only exists if explicitly set.

redirect_url string

The URL to redirect to after checkout is completed with checkoutId, Square's orderId, transactionId, and referenceId appended as URL parameters. For example, if the provided redirect_url is http://www.example.com/order-complete, a successful transaction redirects the customer to:

http://www.example.com/order-complete?checkoutId=xxxxxx&orderId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx

If you do not provide a redirect URL, Square Checkout will display an order confirmation page on your behalf; however Square strongly recommends that you provide a redirect URL so you can verify the transaction results and finalize the order through your existing/normal confirmation workflow.

order Order

Order to be checked out.

created_at string

The time when the checkout was created, in RFC 3339 format.

additional_recipients AdditionalRecipient[]

Additional recipients (other than the merchant) receiving a portion of this checkout. For example, fees assessed on the purchase by a third party integration.

CreateOrderRequest

Fields

Name Type Description
order Order

The order to create. If this field is set, then the only other top-level field that can be set is the idempotency_key.

idempotency_key string

A value you specify that uniquely identifies this order among orders you've created.

If you're unsure whether a particular order was created successfully, you can reattempt it with the same idempotency key without worrying about creating duplicate orders.

See Idempotency for more information.

reference_id DEPRECATED string

Deprecated: Please set the reference_id on the nested order field instead.

An optional ID you can associate with the order for your own purposes (such as to associate the order with an entity ID in your own database).

This value cannot exceed 40 characters.

line_items DEPRECATED CreateOrderRequestLineItem[]

Deprecated: Please set the line_items on the nested order field instead.

The line items to associate with this order.

Each line item represents a different product to include in a purchase.

taxes DEPRECATED CreateOrderRequestTax[]

Deprecated: Please set the taxes on the nested order field instead.

The taxes to include on the order.

discounts DEPRECATED CreateOrderRequestDiscount[]

Deprecated: Please set the discounts on the nested order field instead.

The discounts to include on the order.

CreateOrderRequest Example

          {
  "request_body": {
    "idempotency_key": "8193148c-9586-11e6-99f9-28cfe92138cf",
    "reference_id": "my-order-001",
    "line_items": [
      {
        "name": "New York Strip Steak",
        "quantity": "1",
        "base_price_money": {
          "amount": 1599,
          "currency": "USD"
        }
      },
      {
        "quantity": "2",
        "catalog_object_id": "BEMYCSMIJL46OCDV4KYIKXIB",
        "modifiers": [
          {
            "catalog_object_id": "CHQX7Y4KY6N5KINJKZCFURPZ"
          }
        ],
        "discounts": [
          {
            "name": "Sale - $1.00 off",
            "amount_money": {
              "amount": 100,
              "currency": "USD"
            }
          }
        ]
      }
    ],
    "taxes": [
      {
        "name": "State Sales Tax",
        "percentage": "9"
      }
    ],
    "discounts": [
      {
        "name": "Labor Day Sale",
        "percentage": "5"
      },
      {
        "catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7"
      }
    ]
  }
}
        

CreateOrderRequestDiscount DEPRECATED

Deprecated: Please use the OrderLineItemDiscount type in the order field of CreateOrderRequest instead.

Represents a discount that can apply to either a single line item or an entire order.

Fields

Name Type Description
catalog_object_id string

Only used for catalog discounts. The catalog object ID for an existing CatalogDiscount.

Do not provide a value for this field if you provide values in other fields for an ad hoc discount.

name string

Only used for ad hoc discounts. The discount's name.

percentage string

Only used for ad hoc discounts. The percentage of the discount, as a string representation of a decimal number.

A value of 7.25 corresponds to a percentage of 7.25%. This value range between 0.0 up to 100.0

amount_money Money

Only used for ad hoc discounts. The monetary amount of the discount.

CreateOrderRequestLineItem DEPRECATED

Deprecated: Please use the OrderLineItem type in the order field of CreateOrderRequest instead.

Represents a line item to include in an order. Each line item describes a different product to purchase, with its own quantity and price details.

Line items can either reference objects from the merchant's catalog, or can alternatively specify a name and price instead.

Fields

Name Type Description
name string

Only used for ad hoc line items. The name of the line item. This value cannot exceed 500 characters.

Do not provide a value for this field if you provide a value for catalog_object_id.

quantity string

The quantity to purchase, as a string representation of a number.

This string must have a positive integer value.

base_price_money Money

The base price for a single unit of the line item.

base_price_money is required for ad hoc line items and variable priced CatalogItemVariations. If both catalog_object_id and base_price_money are set, base_price_money will override the CatalogItemVariation's price.

variation_name string

Only used for ad hoc line items. The variation name of the line item. This value cannot exceed 255 characters.

If this value is not set for an ad hoc line item, the default value of Regular is used.

Do not provide a value for this field if you provide a value for the catalog_object_id.

note string

The note of the line item. This value cannot exceed 500 characters.

catalog_object_id string

Only used for Catalog line items. The catalog object ID for an existing CatalogItemVariation.

Do not provide a value for this field if you provide a value for name and base_price_money.

modifiers CreateOrderRequestModifier[]

Only used for Catalog line items. The modifiers to include on the line item.

taxes CreateOrderRequestTax[]

The taxes to include on the line item.

discounts CreateOrderRequestDiscount[]

The discounts to include on the line item.

CreateOrderRequestModifier DEPRECATED

Deprecated: Please use the OrderLineItemModifier type instead.

Represents a modifier applied to a single line item.

Modifiers can reference existing objects in a merchant catalog or be constructed ad hoc at the time of purchase by providing a name and price.

Fields

Name Type Description
catalog_object_id string

The catalog object ID of a CatalogModifier.

name string

Only used for ad hoc modifiers. The name of the modifier. name cannot exceed 255 characters.

Do not provide a value for name if you provide a value for catalog_object_id.

base_price_money Money

The base price for the modifier.

base_price_money is required for ad hoc modifiers. If both catalog_object_id and base_price_money are set, base_price_money will override the predefined CatalogModifier price.

CreateOrderRequestTax DEPRECATED

Deprecated: Please use the OrderLineItemTax type in the order field of CreateOrderRequest instead.

Represents a tax that can apply to either a single line item or an entire order.

Fields

Name Type Description
catalog_object_id string

Only used for catalog taxes. The catalog object ID of an existing CatalogTax.

Do not provide a value for this field if you provide values in other fields for an ad hoc tax.

name string

Only used for ad hoc taxes. The tax's name.

Do not provide a value for this field if you set catalog_object_id.

type string

Only used for ad hoc taxes. Indicates the calculation method used to apply the line item tax.

Default: ADDITIVE; See OrderLineItemTaxType for possible values

percentage string

Only used for ad hoc taxes. The percentage of the tax, as a string representation of a decimal number.

A value of 7.25 corresponds to a percentage of 7.25%. This value range between 0.0 up to 100.0

Customer

Represents one of a business's customers, which can have one or more cards on file associated with it.

Fields

Name Type Description
id string

The customer's unique ID.

created_at string

The time when the customer was created, in RFC 3339 format.

updated_at string

The time when the customer was last updated, in RFC 3339 format.

cards Card[]

The payment details of the customer's cards on file.

given_name string

The customer's given (i.e., first) name.

family_name string

The customer's family (i.e., last) name.

nickname string

The customer's nickname.

company_name string

The name of the customer's company.

email_address string

The customer's email address.

address Address

The customer's physical address.

phone_number string

The customer's phone number.

birthday string

The customer's birthday in RFC-3339 format. Year is optional, timezone and times are not allowed. Example: 0000-09-01T00:00:00-00:00 for a birthday on September 1st. 1998-09-01T00:00:00-00:00 for a birthday on September 1st 1998.

reference_id string

A second ID you can set to associate the customer with an entity in another system.

note string

A note to associate with the customer.

preferences CustomerPreferences

The customer's preferences.

groups CustomerGroupInfo[]

The groups the customer belongs to.

creation_source string

A creation source represents the method used to create the customer profile. See CustomerCreationSource for possible values

CustomerCreationSourceFilter

Creation source filter.

If one or more creation sources are set, customer profiles are included in, or excluded from, the result if they match at least one of the filter criteria.

Fields

Name Type Description
values string[]

The list of creation sources used as filtering criteria. See CustomerCreationSource for possible values

rule string

Indicates whether a customer profile matching the filter criteria should be included in the result or excluded from the result. Default: INCLUDE. See CustomerInclusionExclusion for possible values

CustomerFilter

Represents a set of CustomerQuery filters used to limit the set of Customers returned by SearchCustomers.

Fields

Name Type Description
creation_source CustomerCreationSourceFilter

A filter to select customers based on their creation source.

created_at TimeRange

A filter to select customers based on when they were created.

updated_at TimeRange

A filter to select customers based on when they were updated.

CustomerGroupInfo

Contains some brief information about a customer group with its identifier included.

Fields

Name Type Description
id string

The ID of the customer group.

name string

The name of the customer group.

CustomerPreferences

Represents a particular customer's preferences.

Fields

Name Type Description
email_unsubscribed boolean

The customer has unsubscribed from receiving marketing campaign emails.

CustomerQuery

Represents a query (filtering and sorting criteria) used to search for customer profiles.

Fields

Name Type Description
filter CustomerFilter

A list of filter criteria.

sort CustomerSort

Sort criteria for query results. The default sort behavior is to order customers alphabetically by given_name and last_name.

CustomerSort

Indicates the field to use for sorting customer profiles. For example, by total money spent with the merchant or the date of their first purchase.

Fields

Name Type Description
field string

The field to sort the results on. It could be the total money spent at the merchant, the date of the first visit (etc). See CustomerSortField for possible values

order string

Indicates the order in which results should be displayed based on the value of the sort field. String comparisons use standard alphabetic comparison to determine order. Strings representing numbers are sorted as strings. See SortOrder for possible values

DateRange

A range defined by two dates. Used for filtering a query for Connect v2 objects that have date properties.

Fields

Name Type Description
start_date string

String in YYYY-MM-DD format, e.g. 2017-10-31 per the ISO 8601 extended format for calendar dates. The beginning of a date range (inclusive)

end_date string

String in YYYY-MM-DD format, e.g. 2017-10-31 per the ISO 8601 extended format for calendar dates. The end of a date range (inclusive)

Device

Fields

Name Type Description
id string

The device's Square-issued ID.

name string

The device's merchant-specified name.

Employee

An employee created in the Square Dashboard account of a business. Used by the Labor API.

Fields

Name Type Description
id string

UUID for this Employee.

first_name string

Given (first) name of the employee.

last_name string

Family (last) name of the employee

email string

Email of the employee

phone_number string

Phone number of the employee in E.164 format, i.e. "+12125554250"

location_ids string[]

A list of location IDs where this employee has access.

status string

Specifies the status of the employee being fetched. See EmployeeStatus for possible values

created_at string

A read-only timestamp in RFC 3339 format.

updated_at string

A read-only timestamp in RFC 3339 format.

EmployeeWage

The hourly wage rate that an employee will earn on a Shift for doing the job specified by the title property of this object.

Fields

Name Type Description
id string

UUID for this object.

employee_id string

The Employee that this wage is assigned to.

title string

The job title that this wage relates to.

hourly_rate Money

Can be a custom-set hourly wage or the calculated effective hourly wage based on annual wage and hours worked per week.

Error

Represents an error encountered during a request to the Connect API.

Fields

Name Type Description
category string

The error's high-level category. See ErrorCategory for possible values

code string

The error's specific code. See ErrorCode for possible values

detail string

A human-readable description of the error for debugging purposes.

field string

The name of the field provided in the original request that the error pertains to, if any.

InventoryAdjustment

Represents a change in state or quantity of product inventory at a particular time and location.

Fields

Name Type Description
id string

A unique ID generated by Square for the InventoryAdjustment.

reference_id string

An optional ID provided by the application to tie the InventoryAdjustment to an external system.

from_state string

The InventoryState of the related quantity of items before the adjustment. See InventoryState for possible values

to_state string

The InventoryState of the related quantity of items after the adjustment. See InventoryState for possible values

location_id string

The Square ID of the Location where the related quantity of items are being tracked.

catalog_object_id string

The Square generated ID of the CatalogObject being tracked.

catalog_object_type string

The CatalogObjectType of the CatalogObject being tracked. Tracking is only supported for the ITEM_VARIATION type.

quantity string

The number of items affected by the adjustment as a decimal string. Fractional quantities are not supported.

total_price_money Money

The read-only total price paid for goods associated with the adjustment. Present if and only if to_state is SOLD. Always non-negative.

occurred_at string

A client-generated timestamp in RFC 3339 format that indicates when the adjustment took place. For write actions, the occurred_at timestamp cannot be older than 24 hours or in the future relative to the time of the request.

created_at string

A read-only timestamp in RFC 3339 format that indicates when Square received the adjustment.

source SourceApplication

Read-only information about the application that caused the inventory adjustment.

employee_id string

The Square ID of the Employee responsible for the inventory adjustment.

transaction_id string

The read-only Square ID of the [Transaction][#type-transaction] that caused the adjustment. Only relevant for payment-related state transitions.

refund_id string

The read-only Square ID of the [Refund][#type-refund] that caused the adjustment. Only relevant for refund-related state transitions.

purchase_order_id string

The read-only Square ID of the purchase order that caused the adjustment. Only relevant for state transitions from the Square for Retail app.

goods_receipt_id string

The read-only Square ID of the Square goods receipt that caused the adjustment. Only relevant for state transitions from the Square for Retail app.

InventoryChange

Represents a single physical count, inventory, adjustment, or transfer that is part of the history of inventory changes for a particular CatalogObject.

Fields

Name Type Description
type string

Indicates how the inventory change was applied. See InventoryChangeType for possible values

physical_count InventoryPhysicalCount

Contains details about the physical count when type is PHYSICAL_COUNT and unset for all other types.

adjustment InventoryAdjustment

Contains details about the inventory adjustment when type is ADJUSTMENT and unset for all other types.

transfer InventoryTransfer

Contains details about the inventory transfer when type is TRANSFER and unset for all other types.

InventoryCount

Represents the estimated quantity of items in a particular state at a particular location based on the known history of physical counts and inventory adjustments.

Fields

Name Type Description
catalog_object_id string

The Square generated ID of the CatalogObject being tracked.

catalog_object_type string

The CatalogObjectType of the CatalogObject being tracked. Tracking is only supported for the ITEM_VARIATION type.

state string

The current InventoryState for the related quantity of items. See InventoryState for possible values

location_id string

The Square ID of the Location where the related quantity of items are being tracked.

quantity string

The number of items in the count as a decimal string. Fractional quantities are not supported.

calculated_at string

A read-only timestamp in RFC 3339 format that indicates when Square received the most recent physical count or adjustment that had an affect on the estimated count.

InventoryPhysicalCount

Represents a verified (re)count of items in a given state at a specific location. For example, the quantity of items currently on hand at a physical store).

Fields

Name Type Description
id string

A unique ID generated by Square for the InventoryPhysicalCount.

reference_id string

An optional ID provided by the application to tie the InventoryPhysicalCount to an external system.

catalog_object_id string

The Square generated ID of the CatalogObject being tracked.

catalog_object_type string

The CatalogObjectType of the CatalogObject being tracked. Tracking is only supported for the ITEM_VARIATION type.

state string

The current InventoryState for the related quantity of items. See InventoryState for possible values

location_id string

The Square ID of the Location where the related quantity of items are being tracked.

quantity string

The number of items affected by the physical count as a decimal string. Fractional quantities are not supported.

source SourceApplication

Read-only information about the application that submitted the physical count.

employee_id string

The Square ID of the Employee responsible for the physical count.

occurred_at string

A client-generated timestamp in RFC 3339 format that indicates when the physical count took place. For write actions, the occurred_at timestamp cannot be older than 24 hours or in the future relative to the time of the request.

created_at string

A read-only timestamp in RFC 3339 format that indicates when Square received the physical count.

InventoryTransfer

Represents the transfer of a quantity of product inventory at a particular time from one location to another.

Fields

Name Type Description
id string

A unique ID generated by Square for the InventoryTransfer.

reference_id string

An optional ID provided by the application to tie the InventoryTransfer to an external system.

state string

The InventoryState for the quantity of items being transfered. See InventoryState for possible values

from_location_id string

The Square ID of the Location where the related quantity of items were tracked before the transfer.

to_location_id string

The Square ID of the Location where the related quantity of items were tracked after the transfer.

catalog_object_id string

The Square generated ID of the CatalogObject being tracked.

catalog_object_type string

The CatalogObjectType of the CatalogObject being tracked.Tracking is only supported for the ITEM_VARIATION type.

quantity string

The number of items affected by the transfer as a decimal string. Fractional quantities are not supported.

occurred_at string

A client-generated timestamp in RFC 3339 format that indicates when the transfer took place. For write actions, the occurred_at timestamp cannot be older than 24 hours or in the future relative to the time of the request.

created_at string

A read-only timestamp in RFC 3339 format that indicates when Square received the transfer request.

source SourceApplication

Read-only information about the application that initiated the inventory transfer.

employee_id string

The Square ID of the Employee responsible for the inventory transfer.

ItemVariationLocationOverrides

Price and inventory alerting overrides for a CatalogItemVariation at a specific location.

Fields

Name Type Description
location_id string

The ID of the location.

price_money Money

The price of the CatalogItemVariation at the given location, or blank for variable pricing.

pricing_type string

The pricing type (fixed or variable) for the CatalogItemVariation at the given location. See CatalogPricingType for possible values

track_inventory boolean

If true, inventory tracking is active for the CatalogItemVariation at this location.

inventory_alert_type string

Indicates whether the CatalogItemVariation displays an alert when its inventory quantity is less than or equal to its inventory_alert_threshold. See InventoryAlertType for possible values

inventory_alert_threshold integer

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.

Location

Represents one of a business's locations.

Fields

Name Type Description
id string

The location's unique ID.

name string

The location's name. Location names are set by the account owner and displayed in the dashboard as the location's nickname

address Address

The location's physical address.

timezone string

The IANA Timezone Database identifier for the location's timezone.

capabilities string[]

Indicates which Square features are enabled for the location. See LocationCapability for possible values

status string

The location's status See LocationStatus for possible values

created_at string

The time when the location was created, in RFC 3339 format.

merchant_id string

The identifier of the merchant that owns the location.

country string

The location's country, in ISO 3166-1-alpha-2 format. See Country for possible values

language_code string

The language associated with the location in BCP 47 format.

currency string

The currency used for all transactions at this location, specified in ISO 4217 format. For example, the currency for a location processing transactions in the United States is 'USD'. See Currency for possible values

phone_number string

The location's phone_number.

business_name string

The location's business_name which is shown to its customers. For example, this is the name printed on its customer's receipts.

type string

The location's type, as set by the account owner in the Square dashboard. Typically used to indicate whether or not the location object represents a physical space like a building or mall space. See LocationType for possible values

website_url string

The location's website, as set by the account owner in the Square dashboard.

Default: none; only exists if explicitly set.

Money

Represents an amount of money.

Important: Unlike version 1 of the Connect API, all monetary amounts returned by v2 endpoints are positive. (In v1, monetary amounts are negative if they represent money being paid by a merchant, instead of money being paid to a merchant.)

Fields

Name Type Description
amount integer

The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents.

currency string

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD. See Currency for possible values

Order

Contains all information related to a single order to process with Square, including line items that specify the products to purchase

Fields

Name Type Description
id string

The order's unique ID.

This value is only present for Order objects created by the Orders API through the CreateOrder endpoint.

location_id string

The ID of the merchant location this order is associated with.

reference_id string

A client specified identifier to associate an entity in another system with this order.

source BETA OrderSource

The origination details of the order.

line_items OrderLineItem[]

The line items included in the order.

taxes OrderLineItemTax[]

A list of taxes applied to this order. On read or retrieve, this list includes both order-level and item-level taxes. When creating an Order, set your order-level taxes in this list.

discounts OrderLineItemDiscount[]

A list of discounts applied to this order. On read or retrieve, this list includes both order-level and item-level discounts. When creating an Order, set your order-level discounts in this list.

fulfillments BETA OrderFulfillment[]

Details on order fulfillment.

Orders can only be created with at most one fulfillment. However, orders returned by the API may contain multiple fulfillments.

total_money Money

The total amount of money to collect for the order.

total_tax_money Money

The total tax amount of money to collect for the order.

total_discount_money Money

The total discount amount of money to collect for the order.

OrderFulfillment BETA

Contains details on how to fulfill this order.

Fields

Name Type Description
type string

The type of the fulfillment. See OrderFulfillmentType for possible values

state string

The state of the fulfillment. See OrderFulfillmentState for possible values

pickup_details OrderFulfillmentPickupDetails

Contains pickup-specific details. Required when fulfillment type is PICKUP.

OrderFulfillmentPickupDetails BETA

Contains details necessary to fulfill a pickup order.

Fields

Name Type Description
recipient OrderFulfillmentRecipient

The recipient of this pickup fulfillment.

expires_at string

The expiry timestamp in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". This timestamp indicates when the pickup fulfillment will expire if it is not accepted by the merchant. Expiration time can only be set up to 7 days in the future. If not set, this pickup fulfillment will be automatically accepted when placed.

auto_complete_duration string

The auto completion duration in RFC3339 duration format, e.g., "P1W3D". If set, an open and accepted pickup fulfillment will automatically move to the COMPLETED state after this period of time. If not set, this pickup fulfillment will remain accepted until it is canceled or completed.

schedule_type string

The schedule type of the pickup fulfillment. Defaults to SCHEDULED. See OrderFulfillmentPickupDetailsScheduleType for possible values

pickup_at string

The pickup timestamp in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z". For fulfillments with the schedule type ASAP, this is automatically set to the current time plus the expected duration to prepare the fulfillment. This represents the start of the pickup window.

pickup_window_duration string

The pickup window duration in RFC3339 duration format, e.g., "P1W3D". This duration represents the window of time for which the order should be picked up after the pickup_at time. Can be used as an informational guideline for merchants.

prep_time_duration string

The preparation time duration in RFC3339 duration format, e.g., "P1W3D". This duration indicates how long it takes the merchant to prepare this fulfillment.

note string

A general note about the pickup fulfillment.

Notes are useful for providing additional instructions and are displayed in Square apps.

placed_at string

The timestamp in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z", indicating when the fulfillment was placed.

accepted_at string

The timestamp in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z", indicating when the fulfillment was accepted by the merchant.

rejected_at string

The timestamp in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z", indicating when the fulfillment was rejected.

ready_at string

The timestamp in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z", indicating when the merchant set the fulfillment as ready for pickup.

expired_at string

The timestamp in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z", indicating when the fulfillment expired.

picked_up_at string

The timestamp in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z", indicating when the fulfillment was picked up by the recipient.

canceled_at string

The timestamp in RFC3339 timestamp format, e.g., "2016-09-04T23:59:33.123Z", indicating when the fulfillment was canceled by the merchant or buyer.

cancel_reason string

A description of why the pickup was canceled. Max length is 100 characters.

OrderFulfillmentRecipient BETA

The recipient of a fulfillment.

Fields

Name Type Description
customer_id string

The Customer ID of the customer associated with the fulfillment.

If customer_id is provided, the corresponding recipient information fields (display_name, email_address, and phone_number) are automatically populated from the relevant customer profile. If the targeted profile information does not contain the necessary required information, the request will result in an error.

display_name string

The display name of the fulfillment recipient.

If provided, overrides the value from customer profile indicated by customer_id.

email_address string

The email address of the fulfillment recipient.

If provided, overrides the value from customer profile indicated by customer_id.

phone_number string

The phone number of the fulfillment recipient.

If provided, overrides the value from customer profile indicated by customer_id.

OrderLineItem

Represents a line item in an order. Each line item describes a different product to purchase, with its own quantity and price details.

Fields

Name Type Description
name string

The name of the line item.

quantity string

The quantity purchased, as a string representation of a number.

This string must have a positive integer value.

note string

The note of the line item.

catalog_object_id string

The CatalogItemVariation id applied to this line item.

variation_name string

The name of the variation applied to this line item.

modifiers OrderLineItemModifier[]

The CatalogModifiers applied to this line item.

taxes OrderLineItemTax[]

A list of taxes applied to this line item. On read or retrieve, this list includes both item-level taxes and any order-level taxes apportioned to this item. When creating an Order, set your item-level taxes in this list.

discounts OrderLineItemDiscount[]

A list of discounts applied to this line item. On read or retrieve, this list includes both item-level discounts and any order-level discounts apportioned to this item. When creating an Order, set your item-level discounts in this list.

base_price_money Money

The base price for a single unit of the line item.

gross_sales_money Money

The gross sales amount of money calculated as (item base price + modifiers price) * quantity.

total_tax_money Money

The total tax amount of money to collect for the line item.

total_discount_money Money

The total discount amount of money to collect for the line item.

total_money Money

The total amount of money to collect for this line item.

OrderLineItemDiscount

Represents a discount that applies to one or more line items in an order.

Fixed-amount, order-level discounts are distributed across all non-zero line item totals. The amount distributed to each line item is relative to that item’s contribution to the order subtotal.

Fields

Name Type Description
catalog_object_id string

The catalog object id referencing CatalogDiscount.

name string

The discount's name.

type string

The type of the discount. If it is created by API, it would be either FIXED_PERCENTAGE or FIXED_AMOUNT.

VARIABLE_* is not supported in API because the order is created at the time of sale and either percentage or amount has to be specified. See OrderLineItemDiscountType for possible values

percentage string

The percentage of the tax, as a string representation of a decimal number. A value of 7.25 corresponds to a percentage of 7.25%.

The percentage won't be set for an amount-based discount.

amount_money Money

The total monetary amount of the applicable discount. If it is at order level, it is the value of the order level discount. If it is at line item level, it is the value of the line item level discount.

The amount_money won't be set for a percentage-based discount.

applied_money Money

The amount of discount actually applied to this line item.

Represents the amount of money applied to a line item as a discount When an amount-based discount is at order-level, this value is different from amount_money because the discount is distributed across the line items.

scope string

Indicates the level at which the discount applies. This field is set by the server. If set in a CreateOrder request, it will be ignored on write. See OrderLineItemDiscountScope for possible values

OrderLineItemModifier

A CatalogModifier.

Fields

Name Type Description
catalog_object_id string

The catalog object id referencing CatalogModifier.

name string

The name of the item modifier.

base_price_money Money

The base price for the modifier.

base_price_money is required for ad hoc modifiers. If both catalog_object_id and base_price_money are set, base_price_money will override the predefined CatalogModifier price.

total_price_money Money

The total price of the item modifier for its line item. This is the modifier's base_price_money multiplied by the line item's quantity.

OrderLineItemTax

Represents a tax that applies to one or more line items in an order.

Fields

Name Type Description
catalog_object_id string

The catalog object id referencing CatalogTax.

name string

The tax's name.

type string

Indicates the calculation method used to apply the tax. See OrderLineItemTaxType for possible values

percentage string

The percentage of the tax, as a string representation of a decimal number.

A value of 7.25 corresponds to a percentage of 7.25%.

applied_money Money

The amount of the money applied by the tax in an order.

scope string

Indicates the level at which the tax applies. This field is set by the server. If set in a CreateOrder request, it will be ignored on write. See OrderLineItemTaxScope for possible values

OrderSource BETA

Represents the origination details of an order.

Fields

Name Type Description
name string

The name used to identify the place (physical or digital) that an order originates.

If unset, the name defaults to the name of the application that created the order.

Refund

Represents a refund processed for a Square transaction.

Fields

Name Type Description
id string

The refund's unique ID.

location_id string

The ID of the refund's associated location.

transaction_id string

The ID of the transaction that the refunded tender is part of.

tender_id string

The ID of the refunded tender.

created_at string

The time when the refund was created, in RFC 3339 format.

reason string

The reason for the refund being issued.

amount_money Money

The amount of money refunded to the buyer.

status string

The current status of the refund (PENDING, APPROVED, REJECTED, or FAILED). See RefundStatus for possible values

processing_fee_money Money

The amount of Square processing fee money refunded to the merchant.

additional_recipients AdditionalRecipient[]

Additional recipients (other than the merchant) receiving a portion of this refund. For example, fees assessed on a refund of a purchase by a third party integration.

Shift

A record of the hourly rate, start, and end times for a single work shift for an employee. May include a record of the start and end times for breaks taken during the shift.

Fields

Name Type Description
id string

UUID for this object

employee_id string

The ID of the employee this shift belongs to.

location_id string

The ID of the location this shift occurred at. Should be based on where the employee clocked in.

timezone string

Read-only convenience value that is calculated from the location based on location_id. Format: the IANA Timezone Database identifier for the location timezone.

start_at string

RFC 3339; shifted to location timezone + offset. Precision up to the minute is respected; seconds are truncated.

end_at string

RFC 3339; shifted to timezone + offset. Precision up to the minute is respected; seconds are truncated. The end_at minute is not counted when the shift length is calculated. For example, a shift from 00:00 to 08:01 is considered an 8 hour shift (midnight to 8am).

wage ShiftWage

Job and pay related information.

breaks Break[]

A list of any paid or unpaid breaks that were taken during this shift.

status string

Describes working state of the current Shift. See ShiftStatus for possible values

version integer

Used for resolving concurrency issues; request will fail if version provided does not match server version at time of request. If not provided, Square executes a blind write; potentially overwriting data from another write.

created_at string

A read-only timestamp in RFC 3339 format; presented in UTC.

updated_at string

A read-only timestamp in RFC 3339 format; presented in UTC.

ShiftFilter

Defines a filter used in a search for Shift records. AND logic is used by Square's servers to apply each filter property specified.

Fields

Name Type Description
location_id string[]

Fetch shifts for the specified location.

employee_id string[]

Fetch shifts for the specified employee.

status string

Fetch a Shift instance by Shift.status. See ShiftFilterStatus for possible values

start TimeRange

Fetch Shifts that start in the time range - Inclusive.

end TimeRange

Fetch the Shifts that end in the time range - Inclusive.

workday ShiftWorkday

Fetch the Shifts based on workday date range.

ShiftQuery

The parameters of a Shift search query. Includes filter and sort options.

Fields

Name Type Description
filter ShiftFilter

Query filter options

sort ShiftSort

Sort order details

ShiftSort

Sets the sort order of search results.

Fields

Name Type Description
field string

The field to sort on. See ShiftSortField for possible values

order string

The order in which results are returned. Defaults to DESC. See SortOrder for possible values

ShiftWage

The hourly wage rate used to compensate an employee for this shift.

Fields

Name Type Description
title string

The name of the job performed during this shift. Square labor-reporting UIs may group shifts together by title.

hourly_rate Money

Can be a custom-set hourly wage or the calculated effective hourly wage based on annual wage and hours worked per week.

ShiftWorkday

A Shift search query filter parameter that sets a range of days that a Shift must start or end in before passing the filter condition.

Fields

Name Type Description
date_range DateRange

Dates for fetching the shifts

match_shifts_by string

The strategy on which the dates are applied. See ShiftWorkdayMatcher for possible values

default_timezone string

Location-specific timezones convert workdays to datetime filters. Every location included in the query must have a timezone, or this field must be provided as a fallback. Format: the IANA timezone database identifier for the relevant timezone.

SourceApplication

Provides information about the application used to generate an inventory change.

Fields

Name Type Description
product string

Read-only Product type for the application. See Product for possible values

application_id string

Read-only Square ID assigned to the application. Only used for Product type EXTERNAL_API.

name string

Read-only display name assigned to the application (e.g. "Custom Application", "Square POS 4.74 for Android").

Tender

Represents a tender (i.e., a method of payment) used in a Square transaction.

Fields

Name Type Description
id string

The tender's unique ID.

location_id string

The ID of the transaction's associated location.

transaction_id string

The ID of the tender's associated transaction.

created_at string

The time when the tender was created, in RFC 3339 format.

note string

An optional note associated with the tender at the time of payment.

amount_money Money

The amount of the tender.

tip_money Money

The tip's amount of the tender.

processing_fee_money Money

The amount of any Square processing fees applied to the tender.

This field is not immediately populated when a new transaction is created. It is usually available after about ten seconds.

customer_id string

If the tender is associated with a customer or represents a customer's card on file, this is the ID of the associated customer.

type string

The type of tender, such as CARD or CASH. See TenderType for possible values

card_details TenderCardDetails

The details of the card tender.

This value is present only if the value of type is CARD.

cash_details TenderCashDetails

The details of the cash tender.

This value is present only if the value of type is CASH.

additional_recipients AdditionalRecipient[]

Additional recipients (other than the merchant) receiving a portion of this tender. For example, fees assessed on the purchase by a third party integration.

TenderCardDetails

Represents additional details of a tender with type CARD or SQUARE_GIFT_CARD

Fields

Name Type Description
status string

The credit card payment's current state (such as AUTHORIZED or CAPTURED). See TenderCardDetailsStatus for possible values

card Card

The credit card's non-confidential details.

entry_method string

The method used to enter the card's details for the transaction. See TenderCardDetailsEntryMethod for possible values

TenderCashDetails

Represents the details of a tender with type CASH.

Fields

Name Type Description
buyer_tendered_money Money

The total amount of cash provided by the buyer, before change is given.

change_back_money Money

The amount of change returned to the buyer.

TimeRange

Represents a generic time range. The start and end values are represented in RFC-3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevent endpoint-specific documentation to determine how time ranges are handled.

Fields

Name Type Description
start_at string

A datetime value in RFC-3339 format indicating when the time range starts.

end_at string

A datetime value in RFC-3339 format indicating when the time range ends.

Transaction

Represents a transaction processed with Square, either with the Connect API or with Square Point of Sale.

The tenders field of this object lists all methods of payment used to pay in the transaction.

Fields

Name Type Description
id string

The transaction's unique ID, issued by Square payments servers.

location_id string

The ID of the transaction's associated location.

created_at string

The time when the transaction was created, in RFC 3339 format.

tenders Tender[]

The tenders used to pay in the transaction.

refunds Refund[]

Refunds that have been applied to any tender in the transaction.

reference_id string

If the transaction was created with the Charge endpoint, this value is the same as the value provided for the reference_id parameter in the request to that endpoint. Otherwise, it is not set.

product string

The Square product that processed the transaction. See TransactionProduct for possible values

client_id string

If the transaction was created in the Square Point of Sale app, this value is the ID generated for the transaction by Square Point of Sale.

This ID has no relationship to the transaction's canonical id, which is generated by Square's backend servers. This value is generated for bookkeeping purposes, in case the transaction cannot immediately be completed (for example, if the transaction is processed in offline mode).

It is not currently possible with the Connect API to perform a transaction lookup by this value.

shipping_address Address

The shipping address provided in the request, if any.

order_id string

The order_id is an identifier for the order associated with this transaction, if any.

V1BankAccount

V1BankAccount

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.

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.

type string

The bank account's type (for example, savings or checking). See V1BankAccountType for possible values

V1CashDrawerEvent

V1CashDrawerEvent

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 string

The type of event that occurred. See V1CashDrawerEventEventType for possible values

event_money V1Money

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.

V1CashDrawerShift

V1CashDrawerShift

Fields

Name Type Description
id string

The shift's unique ID.

event_type string

The shift's current state. See V1CashDrawerShiftEventType for possible values

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

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

starting_cash_money V1Money

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

cash_payment_money V1Money

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

cash_refunds_money V1Money

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

cash_paid_in_money V1Money

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

cash_paid_out_money V1Money

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

expected_cash_money V1Money

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 V1Money

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 Register that was connected to the cash drawer.

events V1CashDrawerEvent[]

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

V1Category

V1Category

Fields

Name Type Description
id string

The category's unique ID.

name string

The category's name.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

V1Discount

V1Discount

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.

amount_money V1Money

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 string

Indicates whether the discount is a FIXED value or entered at the time of sale. See V1DiscountDiscountType for possible values

pin_required boolean

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

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1DiscountColor for possible values

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

V1Employee

Represents one of a business's 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.

status string

CWhether the employee is ACTIVE or INACTIVE. Inactive employees cannot sign in to Square Register.Merchants update this field from the Square Dashboard. See V1EmployeeStatus for possible values

external_id string

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

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.

V1EmployeeRole

V1EmployeeRole

Fields

Name Type Description
id string

The role's unique ID, Can only be set by Square.

name string

The role's merchant-defined name.

permissions string[]

The role's permissions. See V1EmployeeRolePermissions for possible values

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 employee entity was created, in ISO 8601 format. Is set by Square when the Role is created.

updated_at string

The time when the employee entity was most recently updated, in ISO 8601 format. Is set by Square when the Role updated.

V1Fee

V1Fee

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 string

Forthcoming See V1FeeCalculationPhase for possible values

adjustment_type string

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

applies_to_custom_amounts boolean

If true, the fee applies to custom amounts entered into Square Register 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 string

Whether the fee is ADDITIVE or INCLUSIVE. See V1FeeInclusionType for possible values

type string

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

V1InventoryEntry

V1InventoryEntry

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.

V1Item

V1Item

Fields

Name Type Description
id 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 (_).

name string

The item's name.

description string

The item's description.

type string

The item's type. This value is NORMAL for almost all items. See V1ItemType for possible values

color string

The color of the discount's display label in Square Register, if not the default color. The default color is 9da2a6. See V1ItemColor for possible values

abbreviation string

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

visibility string

Indicates whether the item is viewable from the merchant's online store (PUBLIC) or PRIVATE. See V1ItemVisibility for possible values

available_online boolean

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

master_image V1ItemImage

The item's master image, if any.

category V1Category

The category the item belongs to, if any.

variations V1Variation[]

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

modifier_lists V1Variation[]

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

fees V1Fee[]

The fees that apply to the item, if any.

taxable boolean

Deprecated. This field is not used.

category_id string

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

available_for_pickup boolean

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

V1ItemImage

V1ItemImage

Fields

Name Type Description
id string

The image's unique ID.

url string

The image's publicly accessible URL.

V1Merchant

Defines the fields that are included in the response body of a request to the RetrieveBusiness endpoint.

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 string

Indicates whether the merchant account corresponds to a single-location account (LOCATION) or a business account (BUSINESS). This value is almost always LOCATION. See V1MerchantAccountType for possible values

account_capabilities string[]

Capabilities that are enabled for the merchant's Square account. Capabilities that are not listed in this array are not enabled for the account.

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 Address

The address of the merchant's business.

business_phone V1PhoneNumber

The phone number of the merchant's business.

business_type string

The type of business operated by the merchant. See V1MerchantBusinessType for possible values

shipping_address Address

The merchant's shipping address.

location_details V1MerchantLocationDetails

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

market_url string

The URL of the merchant's online store.

V1MerchantLocationDetails

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

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's multi-location dashboard.

V1ModifierList

V1ModifierList

Fields

Name Type Description
id string

The modifier list's unique ID.

name string

The modifier list's name.

selection_type string

Indicates whether MULTIPLE options or a SINGLE option from the modifier list can be applied to a single item. See V1ModifierListSelectionType for possible values

modifier_options V1ModifierOption[]

The options included in the modifier list.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

V1ModifierOption

V1ModifierOption

Fields

Name Type Description
id string

The modifier option's unique ID.

name string

The modifier option's name.

price_money V1Money

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 integer

Indicates the modifier option's list position when displayed in Square Register 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.

modifier_list_id string

The ID of the modifier list the option belongs to.

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

V1Money

Fields

Name Type Description
amount integer

Amount in the lowest denominated value of this Currency. E.g. in USD these are cents, in JPY they are Yen (which do not have a 'cent' concept).

currency_code string

See Currency for possible values

V1Page

V1Page

Fields

Name Type Description
id string

The page's unique identifier.

name string

The page's name, if any.

page_index integer

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

cells V1PageCell[]

The cells included on the page.

V1PageCell

V1PageCell

Fields

Name Type Description
page_id string

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

row integer

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

column integer

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

object_type string

The type of entity represented in the cell (ITEM, DISCOUNT, CATEGORY, or PLACEHOLDER). See V1PageCellObjectType for possible values

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 string

For a cell with an object_type of PLACEHOLDER, this value indicates the cell's special behavior. See V1PageCellPlaceholderType for possible values

V1Payment

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 includes several fields that end in _money. These fields describe the various amounts of money that contribute to the payment total:

  • Monetary values are positive if they represent an increase in the amount of money the merchant receives (e.g., tax_money, tip_money).
  • Monetary values are negative if they represent an decrease in the amount of money the merchant receives (e.g., discount_money, refunded_money).

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.

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 V1Money

The sum of all inclusive taxes associated with the payment.

additive_tax_money V1Money

The sum of all additive taxes associated with the payment.

tax_money V1Money

The total of all taxes applied to the payment. This is always the sum of inclusive_tax_money and additive_tax_money.

tip_money V1Money

The total of all tips applied to the payment.

discount_money V1Money

The total of all discounts applied to the payment.

total_collected_money V1Money

The total of all discounts applied to the payment.

processing_fee_money V1Money

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

net_total_money V1Money

The amount to be deposited into the merchant's bank account for the payment.

refunded_money V1Money

The total of all refunds applied to the payment.

swedish_rounding_money V1Money

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 V1Money

The total of all sales, including any applicable taxes.

net_sales_money V1Money

The total of all sales, minus any applicable taxes.

inclusive_tax V1PaymentTax[]

All of the inclusive taxes associated with the payment.

additive_tax V1PaymentTax[]

All of the additive taxes associated with the payment.

tender V1Tender[]

All of the tenders associated with the payment.

refunds V1Refund[]

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 if a merchant chooses to refund money to a tender after previously accepting returned goods as part of an exchange.

itemizations V1PaymentItemization[]

The items purchased in the payment.

surcharge_money V1Money

The total of all surcharges applied to the payment.

surcharges V1PaymentSurcharge[]

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.

V1PaymentDiscount

V1PaymentDiscount

Fields

Name Type Description
name string

The discount's name.

applied_money V1Money

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 Register might not have an ID.

V1PaymentItemDetail

V1PaymentItemDetail

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.

V1PaymentItemization

Payment include anitemizations 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.

Note*: 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.

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 string

The type of purchase that the itemization represents, such as an ITEM or CUSTOM_AMOUNT See V1PaymentItemizationItemizationType for possible values

item_detail V1PaymentItemDetail

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 V1Money

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

single_quantity_money V1Money

The cost of a single unit of this item.

gross_sales_money V1Money

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

discount_money V1Money

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

net_sales_money V1Money

The sum of gross_sales_money and discount_money.

taxes V1PaymentTax[]

All taxes applied to this itemization.

discounts V1PaymentDiscount[]

All discounts applied to this itemization.

modifiers V1PaymentModifier[]

All modifier options applied to this itemization.

V1PaymentModifier

V1PaymentModifier

Fields

Name Type Description
name string

The modifier option's name.

applied_money V1Money

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

modifier_option_id string

TThe ID of the applied modifier option, if available. Modifier options applied in older versions of Square Register might not have an ID.

V1PaymentSurcharge

V1PaymentSurcharge

Fields

Name Type Description
name string

The name of the surcharge.

applied_money V1Money

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 V1Money

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

type string

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

taxable boolean

Indicates whether the surcharge is taxable.

taxes V1PaymentTax[]

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

surcharge_id string

A Square-issued unique identifier associated with the surcharge.

V1PaymentTax

V1PaymentTax

Fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

name string

The merchant-defined name of the tax.

applied_money V1Money

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 string

Whether the tax is an ADDITIVE tax or an INCLUSIVE tax. See V1PaymentTaxInclusionType for possible values

fee_id string

The ID of the tax, if available. Taxes applied in older versions of Square Register might not have an ID.

V1PhoneNumber

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.

V1Refund

V1Refund

Fields

Name Type Description
type string

The type of refund See V1RefundType for possible values

reason string

The merchant-specified reason for the refund.

refunded_money V1Money

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

refunded_processing_fee_money V1Money

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

refunded_tax_money V1Money

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

refunded_additive_tax_money V1Money

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

refunded_additive_tax V1PaymentTax[]

All of the additive taxes associated with the refund.

refunded_inclusive_tax_money V1Money

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

refunded_inclusive_tax V1PaymentTax[]

All of the inclusive taxes associated with the refund.

refunded_tip_money V1Money

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

refunded_discount_money V1Money

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

refunded_surcharge_money V1Money

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

refunded_surcharges V1PaymentSurcharge[]

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

A Square-issued ID associated with the refund. For single-tender refunds, payment_id is the ID of the original payment ID. For split-tender refunds, payment_id is the ID of the original tender. For exchange-based refunds (is_exchange == true), payment_id is the ID of the original payment ID even if the payment includes other tenders.

merchant_id string
is_exchange boolean

Indicates whether or not the refund is associated with an exchange. If is_exchange is true, the refund reflects the value of goods returned in the exchange not the total money refunded.

V1Settlement

V1Settlement

Fields

Name Type Description
id string

The settlement's unique identifier.

status string

The settlement's current status. See V1SettlementStatus for possible values

total_money V1Money

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.

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.

entries V1SettlementEntry[]

The entries included in this settlement.

V1SettlementEntry

V1SettlementEntry

Fields

Name Type Description
payment_id string

The settlement's unique identifier.

type string

The settlement's current status. See V1SettlementEntryType for possible values

amount_money V1Money

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

fee_money V1Money

The amount of all Square fees associated with this settlement entry. This value is always negative or zero.

V1Tender

A tender represents a discrete monetary exchange. Square represents this exchange as a money object with a specific currency and amount, where the amount is given in the smallest denomination of the given currency.

Square POS 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:

The receipt_url for a split tender 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.

A note on gift cards*: 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 that gift card is used as a tender, the balance of the gift card is reduced and the merchant receives no funds. A Tender object with a type of SQUARE_GIFT_CARD indicates a gift card was used for some or all of the associated payment.

Fields

Name Type Description
id string

The tender's unique ID.

type string

The type of tender. See V1TenderType for possible values

name string

A human-readable description of the tender.

employee_id string

The ID of the employee that processed the tender.

receipt_url string

The URL of the receipt for the tender.

card_brand string

The brand of credit card provided. See V1TenderCardBrand for possible values

pan_suffix string

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

entry_method string

The tender's unique ID. See V1TenderEntryMethod for possible values

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 type: OTHER.

total_money V1Money

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

tendered_money V1Money

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 V1Money

The amount of total_money returned to the buyer as change.

refunded_money V1Money

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

is_exchange boolean

Indicates whether or not the tender is associated with an exchange. If is_exchange is true, the tender represents the value of goods returned in an exchange not the actual money paid. The exchange value reduces the tender amounts needed to pay for items purchased in the exchange.

V1Timecard

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 clock-in time for the timecard, in ISO 8601 format.

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

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

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.

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.

V1TimecardEvent

V1TimecardEvent

Fields

Name Type Description
id string

The event's unique ID.

event_type string

The ID of the timecard to list events for. See V1TimecardEventEventType for possible values

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.

V1Variation

V1Variation

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 integer

Indicates the variation's list position when displayed in Square Register 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

pricing_type string

Indicates whether the item variation's price is fixed or determined at the time of sale. See V1VariationPricingType for possible values

price_money V1Money

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 string

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

inventory_alert_threshold integer

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.

user_data string

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

v2_id string

The ID of the CatalogObject in the Connect v2 API. Objects that are shared across multiple locations share the same v2 ID.

WorkweekConfig

Sets the Day of the week and hour of the day that a business starts a work week. Used for the calculation of overtime pay.

Fields

Name Type Description
id string

UUID for this object

start_of_week string

The day of the week on which a business week cuts over for compensation purposes. See Weekday for possible values

start_of_day_local_time string

The local time at which a business week cuts over. Represented as a string in HH:MM format (HH:MM:SS is also accepted, but seconds are truncated).

version integer

Used for resolving concurrency issues; request will fail if version provided does not match server version at time of request. If not provided, Square executes a blind write; potentially overwriting data from another write.

created_at string

A read-only timestamp in RFC 3339 format; presented in UTC

updated_at string

A read-only timestamp in RFC 3339 format; presented in UTC

API Enums

Some Square API enums include the value OTHER. Responses that currently include the value OTHER might have a different value at a later date, when an appropriate value has been added to the enum. Enum values besides OTHER never change retroactively.

CardBrand

Indicates a card's brand, such as VISA or MASTERCARD.

Fields

Name Description
OTHER_BRAND
VISA
MASTERCARD
AMERICAN_EXPRESS
DISCOVER
DISCOVER_DINERS
JCB
CHINA_UNIONPAY
SQUARE_GIFT_CARD

CatalogDiscountType

How to apply a CatalogDiscount to a CatalogItem.

Fields

Name Description
FIXED_PERCENTAGE

Apply the discount as a fixed percentage (e.g., 5%) off the item price.

FIXED_AMOUNT

Apply the discount as a fixed amount (e.g., $1.00) off the item price.

VARIABLE_PERCENTAGE

Apply the discount as a variable percentage off the item price. The percentage will be specified at the time of sale.

VARIABLE_AMOUNT

Apply the discount as a variable amount off the item price. The amount will be specified at the time of sale.

CatalogItemProductType

The type of a CatalogItem. Connect V2 only allows the creation of REGULAR items.

Fields

Name Description
REGULAR

An ordinary item.

GIFT_CARD

A Square gift card.

APPOINTMENTS_SERVICE

A service that can be booked using the Square Appointments app.

RETAIL_ITEM

An item associated with the Retail vertical.

RESTAURANT_ITEM

An item associated with the Restaurants vertical.

CatalogModifierListSelectionType

Indicates whether a CatalogModifierList supports multiple selections.

Fields

Name Description
SINGLE

Indicates that a CatalogModifierList allows only a single CatalogModifier to be selected.

MULTIPLE

Indicates that a CatalogModifierList allows multiple CatalogModifier to be selected.

CatalogObjectType

Possible kinds of CatalogObjects returned from the Catalog, each containing type-specific properties in the *_data field corresponding to the object type.

Fields

Name Description
ITEM

An item, corresponding to CatalogItem. The item-specific data will be stored in the item_data field.

IMAGE

An image, corresponding to CatalogImage. The image-specific data will be stored in the image_data field.

CATEGORY

A category, corresponding to CatalogCategory. The category-specific data will be stored in the category_data field.

ITEM_VARIATION

An item variation, corresponding to CatalogItemVariation. The item variation-specific data will be stored in the item_variation_data field.

TAX

A tax, corresponding to CatalogTax. The tax-specific data will be stored in the tax_data field.

DISCOUNT

A discount, corresponding to CatalogDiscount. The discount-specific data will be stored in the discount_data field.

MODIFIER_LIST

A modifier list, corresponding to CatalogModifierList. The modifier list-specific data will be stored in the modifier_list_data field.

MODIFIER

A modifier, corresponding to CatalogModifier. The modifier-specific data will be stored in the modifier_data field.

CatalogPricingType

Indicates whether the price of a CatalogItemVariation should be entered manually at the time of sale.

Fields

Name Description
FIXED_PRICING

The CatalogItemVariation's price is fixed.

VARIABLE_PRICING

The CatalogItemVariation's price is entered at the time of sale.

Country

Indicates the country associated with another entity, such as a business. Values are in ISO 3166-1-alpha-2 format.

Fields

Name Description
ZZ
AD
AE
AF
AG
AI
AL
AM
AO
AQ
AR
AS
AT
AU
AW
AX
AZ
BA
BB
BD
BE
BF
BG
BH
BI
BJ
BL
BM
BN
BO
BQ
BR
BS
BT
BV
BW
BY
BZ
CA
CC
CD
CF
CG
CH
CI
CK
CL
CM
CN
CO
CR
CU
CV
CW
CX
CY
CZ
DE
DJ
DK
DM
DO
DZ
EC
EE
EG
EH
ER
ES
ET
FI
FJ
FK
FM
FO
FR
GA
GB
GD
GE
GF
GG
GH
GI
GL
GM
GN
GP
GQ
GR
GS
GT
GU
GW
GY
HK
HM
HN
HR
HT
HU
ID
IE
IL
IM
IN
IO
IQ
IR
IS
IT
JE
JM
JO
JP
KE
KG
KH
KI
KM
KN
KP
KR
KW
KY
KZ
LA
LB
LC
LI
LK
LR
LS
LT
LU
LV
LY
MA
MC
MD
ME
MF
MG
MH
MK
ML
MM
MN
MO
MP
MQ
MR
MS
MT
MU
MV
MW
MX
MY
MZ
NA
NC
NE
NF
NG
NI
NL
NO
NP
NR
NU
NZ
OM
PA
PE
PF
PG
PH
PK
PL
PM
PN
PR
PS
PT
PW
PY
QA
RE
RO
RS
RU
RW
SA
SB
SC
SD
SE
SG
SH
SI
SJ
SK
SL
SM
SN
SO
SR
SS
ST
SV
SX
SY
SZ
TC
TD
TF
TG
TH
TJ
TK
TL
TM
TN
TO
TR
TT
TV
TW
TZ
UA
UG
UM
US
UY
UZ
VA
VC
VE
VG
VI
VN
VU
WF
WS
YE
YT
ZA
ZM
ZW

Currency

Indicates the associated currency for an amount of money. Values correspond to ISO 4217.

Fields

Name Description
UNKNOWN_CURRENCY
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
AWG
AZN
BAM
BBD
BDT
BGN
BHD
BIF
BMD
BND
BOB
BOV
BRL
BSD
BTN
BWP
BYR
BZD
CAD
CDF
CHE
CHF
CHW
CLF
CLP
CNY
COP
COU
CRC
CUC
CUP
CVE
CZK
DJF
DKK
DOP
DZD
EGP
ERN
ETB
EUR
FJD
FKP
GBP
GEL
GHS
GIP
GMD
GNF
GTQ
GYD
HKD
HNL
HRK
HTG
HUF
IDR
ILS
INR
IQD
IRR
ISK
JMD
JOD
JPY
KES
KGS
KHR
KMF
KPW
KRW
KWD
KYD
KZT
LAK
LBP
LKR
LRD
LSL
LTL
LVL
LYD
MAD
MDL
MGA
MKD
MMK
MNT
MOP
MRO
MUR
MVR
MWK
MXN
MXV
MYR
MZN
NAD
NGN
NIO
NOK
NPR
NZD
OMR
PAB
PEN
PGK
PHP
PKR
PLN
PYG
QAR
RON
RSD
RUB
RWF
SAR
SBD
SCR
SDG
SEK
SGD
SHP
SLL
SOS
SRD
SSP
STD
SVC
SYP
SZL
THB
TJS
TMT
TND
TOP
TRY
TTD
TWD
TZS
UAH
UGX
USD
USN
USS
UYI
UYU
UZS
VEF
VND
VUV
WST
XAF
XAG
XAU
XBA
XBB
XBC
XBD
XCD
XDR
XOF
XPD
XPF
XPT
XTS
XXX
YER
ZAR
ZMK
ZMW
BTC

CustomerCreationSource

Indicates the method used to create the customer profile.

Fields

Name Description
OTHER

Default creation source. Typically used for backward/future compatibility when the original source of a customer profile is unrecognized. For example, when older clients do not support newer source types.

APPOINTMENTS

Customer profile created automatically when an appointment was scheduled.

COUPON

Customer profile created automatically when a coupon was issued using Square Point of Sale.

DELETION_RECOVERY

Customer profile restored through Square's deletion recovery process.

DIRECTORY

Customer profile created manually through Square Dashboard or Point of Sale application.

EGIFTING

Customer profile created automatically when a gift card was issued using Square Point of Sale. Customer profiles are created for both the purchaser and the recipient of the gift card.

EMAIL_COLLECTION

Customer profile created through Square Point of Sale when signing up for marketing emails during checkout.

FEEDBACK

Customer profile created automatically when providing feedback through a digital receipt.

IMPORT

Customer profile created automatically when importing customer data through Square Dashboard.

INVOICES

Customer profile created automatically during an invoice payment.

LOYALTY

Customer profile created automatically when customers provide a phone number for loyalty reward programs during checkout.

MARKETING

Customer profile created as the result of a campaign managed through Square’s Facebook integration.

MERGE

Customer profile created as the result of explicitly merging multiple customer profiles through the Square Dashboard or Point of Sale application.

ONLINE_STORE

Customer profile created through Square's Online Store solution (legacy service).

INSTANT_PROFILE

Customer profile created automatically as the result of a successful transaction that did not explicitly link to an existing customer profile.

TERMINAL

Customer profile created through Square's Virtual Terminal.

THIRD_PARTY

Customer profile created through a Square API call.

THIRD_PARTY_IMPORT

Customer profile created by a third-party product and imported through an official integration.

UNMERGE_RECOVERY

Customer profile restored through Square's unmerge recovery process.

CustomerInclusionExclusion

Indicates whether customers should be included in, or excluded from, the result set when they match the filtering criteria.

Fields

Name Description
INCLUDE

Customers should be included in the result set when they match the filtering criteria.

EXCLUDE

Customers should be excluded from the result set when they match the filtering criteria.

CustomerSortField

Indicates the sort criteria for a list of Customers.

Fields

Name Description
DEFAULT

Use the default sort. By default, Customers are sorted alphanumerically by concatenating given_name and family_name. If neither name field is set, string comparison is performed using one of the remaining fields in the following order: company_name, email, phone_number.

CREATED_AT

Sort Customers by their creation date (created_at).

EmployeeStatus

The status of the Employee being retrieved.

Fields

Name Description
ACTIVE

Specifies that the employee is in the Active state.

INACTIVE

Specifies that the employee is in the Inactive state.

ErrorCategory

Indicates which high-level category of error has occurred during a request to the Connect API.

Fields

Name Description
API_ERROR

An error occurred with the Connect API itself.

AUTHENTICATION_ERROR

An authentication error occurred. Most commonly, the request had a missing, malformed, or otherwise invalid Authorization header.

INVALID_REQUEST_ERROR

The request was invalid. Most commonly, a required parameter was missing, or a provided parameter had an invalid value.

RATE_LIMIT_ERROR

Your application reached the Connect API rate limit. Retry your request after a while.

PAYMENT_METHOD_ERROR

An error occurred while processing a payment method. Most commonly, the details of the payment method were invalid (such as a card's CVV or expiration date).

REFUND_ERROR

An error occurred while attempting to process a refund.

ErrorCode

Indicates specific errors that can occur during a request to the Connect API.

Fields

Name Description
INTERNAL_SERVER_ERROR
UNAUTHORIZED
ACCESS_TOKEN_EXPIRED
ACCESS_TOKEN_REVOKED
FORBIDDEN
INSUFFICIENT_SCOPES
APPLICATION_DISABLED
V1_APPLICATION
V1_ACCESS_TOKEN
CARD_PROCESSING_NOT_ENABLED
BAD_REQUEST
MISSING_REQUIRED_PARAMETER
INCORRECT_TYPE
INVALID_TIME
INVALID_TIME_RANGE
INVALID_VALUE
INVALID_CURSOR
UNKNOWN_QUERY_PARAMETER
CONFLICTING_PARAMETERS
EXPECTED_JSON_BODY
INVALID_SORT_ORDER
VALUE_REGEX_MISMATCH
VALUE_TOO_SHORT
VALUE_TOO_LONG
VALUE_TOO_LOW
VALUE_TOO_HIGH
VALUE_EMPTY
ARRAY_LENGTH_TOO_LONG
ARRAY_LENGTH_TOO_SHORT
ARRAY_EMPTY
EXPECTED_BOOLEAN
EXPECTED_INTEGER
EXPECTED_FLOAT
EXPECTED_STRING
EXPECTED_OBJECT
EXPECTED_ARRAY
EXPECTED_MAP
EXPECTED_BASE64_ENCODED_BYTE_ARRAY
INVALID_ARRAY_VALUE
INVALID_ENUM_VALUE
INVALID_CONTENT_TYPE
INVALID_FORM_VALUE
ONE_INSTRUMENT_EXPECTED
NO_FIELDS_SET
DEPRECATED_FIELD_SET
CARD_EXPIRED
INVALID_EXPIRATION
INVALID_EXPIRATION_YEAR
INVALID_EXPIRATION_DATE
UNSUPPORTED_CARD_BRAND
UNSUPPORTED_ENTRY_METHOD
INVALID_ENCRYPTED_CARD
INVALID_CARD
DELAYED_TRANSACTION_EXPIRED
DELAYED_TRANSACTION_CANCELED
DELAYED_TRANSACTION_CAPTURED
DELAYED_TRANSACTION_FAILED
CARD_TOKEN_EXPIRED
CARD_TOKEN_USED
AMOUNT_TOO_HIGH
UNSUPPORTED_INSTRUMENT_TYPE
REFUND_AMOUNT_INVALID
REFUND_ALREADY_PENDING
PAYMENT_NOT_REFUNDABLE
INVALID_CARD_DATA
LOCATION_MISMATCH
IDEMPOTENCY_KEY_REUSED
UNEXPECTED_VALUE
SANDBOX_NOT_SUPPORTED
INVALID_EMAIL_ADDRESS
INVALID_PHONE_NUMBER
CHECKOUT_EXPIRED
BAD_CERTIFICATE
CARD_DECLINED
VERIFY_CVV_FAILURE
VERIFY_AVS_FAILURE
CARD_DECLINED_CALL_ISSUER
NOT_FOUND
APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND
METHOD_NOT_ALLOWED
NOT_ACCEPTABLE
REQUEST_TIMEOUT
CONFLICT
REQUEST_ENTITY_TOO_LARGE
UNSUPPORTED_MEDIA_TYPE
RATE_LIMITED
NOT_IMPLEMENTED
SERVICE_UNAVAILABLE
GATEWAY_TIMEOUT

InventoryAlertType

Indicates whether Square should alert the merchant when the inventory quantity of a CatalogItemVariation is low.

Fields

Name Description
NONE

The variation does not display an alert.

LOW_QUANTITY

The variation generates an alert when its quantity is low.

InventoryChangeType

Indicates how the inventory change was applied to a tracked quantity of items.

Fields

Name Description
PHYSICAL_COUNT

The change occurred as part of a physical count update.

ADJUSTMENT

The change occurred as part of the normal lifecycle of goods (e.g., as an inventory adjustment).

TRANSFER

The change occurred as part of an inventory transfer.

InventoryState

Indicates the state of a tracked item quantity in the lifecycle of goods.

Fields

Name Description
CUSTOM

The related quantity of items are in a custom state. READ-ONLY: the Inventory API cannot move quantities to or from this state.

IN_STOCK

The related quantity of items are on hand and available for sale.

SOLD

The related quantity of items were sold as part of an itemized transaction. Quantities in the SOLD state are no longer tracked.

RETURNED_BY_CUSTOMER

The related quantity of items were returned through the Square Point of Sale application, but are not yet available for sale. READ-ONLY: the Inventory API cannot move quantities to or from this state.

RESERVED_FOR_SALE

The related quantity of items are on hand, but not currently available for sale. READ-ONLY: the Inventory API cannot move quantities to or from this state.

SOLD_ONLINE

The related quantity of items were sold online. READ-ONLY: the Inventory API cannot move quantities to or from this state.

ORDERED_FROM_VENDOR

The related quantity of items were ordered from a vendor but not yet received. READ-ONLY: the Inventory API cannot move quantities to or from this state.

RECEIVED_FROM_VENDOR

The related quantity of items were received from a vendor but are not yet available for sale. READ-ONLY: the Inventory API cannot move quantities to or from this state.

IN_TRANSIT_TO

The related quantity of items are in transit between locations. READ-ONLY*: the Inventory API cannot move quantities to or from this state.

NONE

A placeholder indicating that the related quantity of items are not currently tracked in Square. Transferring quantities from the NONE state to a tracked state (e.g., IN_STOCK) introduces stock into the system.

WASTE

The related quantity of items are lost or damaged and cannot be sold.

UNLINKED_RETURN

The related quantity of items were returned but not linked to a previous transaction. Unlinked returns are not tracked in Square. Transferring a quantity from UNLINKED_RETURN to a tracked state (e.g., IN_STOCK) introduces new stock into the system.

LocationCapability

Indicates payment capabilities that a business's location might or might not have enabled.

Fields

Name Description
CREDIT_CARD_PROCESSING

The location can process credit cards with Square.

If this value is not present in a Location's' capabilities array, the location cannot process credit cards.

LocationStatus

Indicates the location's status.

Fields

Name Description
ACTIVE

A fully operational location. The location can be used across all Square products and APIs.

INACTIVE

A functionally limited location. The location can only be used via Square APIs.

NOTE: We strongly discourage the use of inactive locations. Making API calls with inactive locations will cause complications if the restrictions on inactive locations increase in the future.

LocationType

Indicates the location's type.

Fields

Name Description
PHYSICAL

A physical location of a business.

MOBILE

A location without a physical address. For example: mobile food truck, online store, phone app.

OrderFulfillmentPickupDetailsScheduleType BETA

The schedule type of the pickup fulfillment.

Fields

Name Description
SCHEDULED

Indicates the fulfillment will be picked up at a scheduled pickup time.

ASAP

Indicates the fulfillment should be prepared immediately.

OrderFulfillmentState BETA

The state of the fulfillment.

Fields

Name Description
PROPOSED

Indicates the fulfillment has been proposed.

RESERVED

Indicates the fulfillment has been reserved.

PREPARED

Indicates the fulfillment has been prepared.

COMPLETED

Indicates the fulfillment was successfully completed.

CANCELED

Indicates the fulfillment was canceled by either the merchant or buyer.

FAILED

Indicates the fulfillment failed to be completed but was not explicitly canceled.

OrderFulfillmentType BETA

The type of fulfillment.

Fields

Name Description
PICKUP

A fulfillment to be picked up by a recipient.

OrderLineItemDiscountScope

Indicates whether this is a line item or order level discount.

Fields

Name Description
OTHER_DISCOUNT_SCOPE

Used for reporting only. The original transaction discount scope is currently not supported by the API.

LINE_ITEM

The discount should be applied to a single line item.

ORDER

The discount should be applied to the entire order.

OrderLineItemDiscountType

Indicates how the discount is applied to the associated line item or order.

Fields

Name Description
UNKNOWN_DISCOUNT

Used for reporting only. The original transaction discount type is currently not supported by the API.

FIXED_PERCENTAGE

Apply the discount as a fixed percentage (e.g., 5%) off the item price.

FIXED_AMOUNT

Apply the discount as a fixed monetary value (e.g., $1.00) off the item price.

VARIABLE_PERCENTAGE

Apply the discount as a variable percentage off the item price.

The variable percentage is defined in Register POS apps. Specific value is assigned at the time of the purchase.

VARIABLE_AMOUNT

Apply the discount as a variable amount off the item price.

The variable amount is defined in Square POS app. Specific value is assigned at the time of the purchase.

OrderLineItemTaxScope

Indicates whether this is a line item or order level tax.

Fields

Name Description
OTHER_TAX_SCOPE

Used for reporting only. The original transaction tax scope is currently not supported by the API.

LINE_ITEM

The tax should be applied to a single line item.

ORDER

The tax should be applied to the entire order.

OrderLineItemTaxType

Indicates how the tax is applied to the associated line item or order.

Fields

Name Description
UNKNOWN_TAX

Used for reporting only. The original transaction tax type is currently not supported by the API.

ADDITIVE

The tax is an additive tax. The tax amount is added on top of the price. For example, a $1.00 item with a 10% additive tax would have a total cost to the buyer of $1.10.

INCLUSIVE

The tax is an inclusive tax. Inclusive taxes are already included in the line item price or order total. For example, a $1.00 item with a 10% inclusive tax would have a pre-tax cost of $0.91 (91 cents) and a $0.09 (9 cents) tax for a total cost of $1 to the buyer.

Product

Indicates the Square product used to generate an inventory change.

Fields

Name Description
SQUARE_POS

Square Point of Sale application.

EXTERNAL_API

Square Connect APIs (Transactions API, Checkout API).

BILLING

A Square subscription (various products).

APPOINTMENTS

Square Appointments.

INVOICES

Square Invoices.

ONLINE_STORE

Square Online Store.

PAYROLL

Square Payroll.

DASHBOARD

Square Dashboard

ITEM_LIBRARY_IMPORT

Item Library Import

OTHER

A Square product that does not match any other value.

RefundStatus

Indicates a refund's current status.

Fields

Name Description
PENDING

The refund is pending.

APPROVED

The refund has been approved by Square.

REJECTED

The refund has been rejected by Square.

FAILED

The refund failed.

RegisterDomainResponseStatus

The status of domain registration.

Fields

Name Description
PENDING

The domain is added, but not verified.

VERIFIED

The domain is added and verified. It can be used to accept Apple Pay transactions.

ShiftFilterStatus

Specifies the status of Shift records to be returned.

Fields

Name Description
OPEN

Shifts that have been started and not ended.

CLOSED

Shifts that have been started and ended.

ShiftSortField

Enumerates the Shift fields to sort on.

Fields

Name Description
START_AT

The start date/time of a Shift

END_AT

The end date/time of a Shift

CREATED_AT

The date/time that a Shift is created

UPDATED_AT

The most recent date/time that a Shift is updated

ShiftStatus

Enumerates the possible status of a Shift

Fields

Name Description
OPEN

Employee started a work shift and the shift is not complete

CLOSED

Employee started and ended a work shift.

ShiftWorkdayMatcher

Defines the logic used to apply a workday filter.

Fields

Name Description
START_AT

All shifts that start on or after the specified workday

END_AT

All shifts that end on or before the specified workday

INTERSECTION

All shifts that start between the start and end workdays (inclusive)

SortOrder

The order (e.g., chronological or alphabetical) in which results from a request are returned.

Fields

Name Description
DESC

The results are returned in descending (e.g., newest-first or Z-A) order.

ASC

The results are returned in ascending (e.g., oldest-first or A-Z) order.

TaxCalculationPhase

When to calculate the taxes due on a cart.

Fields

Name Description
TAX_SUBTOTAL_PHASE

The fee is calculated based on the payment's subtotal.

TAX_TOTAL_PHASE

The fee is calculated based on the payment's total.

TaxInclusionType

Whether to the tax amount should be additional to or included in to the CatalogItem price.

Fields

Name Description
ADDITIVE

The tax is an additive tax. The tax amount is added on top of the CatalogItemVariation price. For example, a $1.00 item with a 10% additive tax would have a total cost to the buyer of $1.10.

INCLUSIVE

The tax is an inclusive tax. The tax amount is included in the CatalogItemVariation price. For example, a $1.00 item with a 10% inclusive tax would have a total cost to the buyer of $1.00, with $0.91 (91 cents) of that total being the cost of the item and $0.09 (9 cents) being tax.

TenderCardDetailsEntryMethod

Indicates the method used to enter the card's details.

Fields

Name Description
SWIPED

The card was swiped through a Square reader or Square stand.

KEYED

The card information was keyed manually into Square Point of Sale or a Square-hosted web form.

EMV

The card was processed via EMV with a Square reader.

ON_FILE

The buyer's card details were already on file with Square.

CONTACTLESS

The card was processed via a contactless (i.e., NFC) transaction with a Square reader.

TenderCardDetailsStatus

Indicates the card transaction's current status.

Fields

Name Description
AUTHORIZED

The card transaction has been authorized but not yet captured.

CAPTURED

The card transaction was authorized and subsequently captured (i.e., completed).

VOIDED

The card transaction was authorized and subsequently voided (i.e., canceled).

FAILED

The card transaction failed.

TenderType

Indicates a tender's type.

Fields

Name Description
CARD

A credit card.

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.

SQUARE_GIFT_CARD

A Square gift card.

NO_SALE

This tender represents the register being opened for a "no sale" event.

OTHER

A form of tender that does not match any other value.

TransactionProduct

Indicates the Square product used to process a transaction.

Fields

Name Description
REGISTER

Square Point of Sale.

EXTERNAL_API

The Square Connect API.

BILLING

A Square subscription for one of multiple products.

APPOINTMENTS

Square Appointments.

INVOICES

Square Invoices.

ONLINE_STORE

Square Online Store.

PAYROLL

Square Payroll.

OTHER

A Square product that does not match any other value.

V1AdjustInventoryRequestAdjustmentType

Fields

Name Description
SALE
RECEIVE_STOCK
MANUAL_ADJUST

V1BankAccountType

Fields

Name Description
BUSINESS_CHECKING
CHECKING
INVESTMENT
LOAN
SAVINGS
OTHER

V1CashDrawerEventEventType

Fields

Name Description
NO_SALE
CASH_TENDER_PAYMENT
OTHER_TENDER_PAYMENT
CASH_TENDER_CANCELED_PAYMENT
OTHER_TENDER_CANCELED_PAYMENT
CASH_TENDER_REFUND
OTHER_TENDER_REFUND
PAID_IN
PAID_OUT

V1CashDrawerShiftEventType

Fields

Name Description
OPEN
ENDED
CLOSED

V1CreateRefundRequestType

Fields

Name Description
FULL
PARTIAL

V1DiscountColor

Fields

Name Description
9da2a6
4ab200
0b8000
2952cc
a82ee5
e5457a
b21212
593c00
e5BF00

V1DiscountDiscountType

Fields

Name Description
FIXED
VARIABLE_PERCENTAGE
VARIABLE_AMOUNT

V1EmployeeRolePermissions

Fields

Name Description
REGISTER_ACCESS_SALES_HISTORY
REGISTER_APPLY_RESTRICTED_DISCOUNTS
REGISTER_CHANGE_SETTINGS
REGISTER_EDIT_ITEM
REGISTER_ISSUE_REFUNDS
REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE
REGISTER_VIEW_SUMMARY_REPORTS

V1EmployeeStatus

Fields

Name Description
ACTIVE
INACTIVE

V1FeeAdjustmentType

Fields

Name Description
TAX

V1FeeCalculationPhase

Fields

Name Description
FEE_SUBTOTAL_PHASE
OTHER
FEE_TOTAL_PHASE

V1FeeInclusionType

Fields

Name Description
ADDITIVE
INCLUSIVE

V1FeeType

Fields

Name Description
CA_GST
CA_HST
CA_PST
CA_QST
JP_CONSUMPTION_TAX
CA_PEI_PST
US_SALES_TAX
OTHER

V1ItemColor

Fields

Name Description
9da2a6
4ab200
0b8000
2952cc
a82ee5
e5457a
b21212
593c00
e5BF00

V1ItemType

Fields

Name Description
NORMAL
GIFT_CARD
OTHER

V1ItemVisibility

Fields

Name Description
PUBLIC
PRIVATE

V1ListEmployeesRequestStatus

Fields

Name Description
ACTIVE
INACTIVE

V1ListSettlementsRequestStatus

Fields

Name Description
SENT
FAILED

V1MerchantAccountType

Fields

Name Description
LOCATION
BUSINESS

V1MerchantBusinessType

Fields

Name Description
ACCOUNTING
APPAREL_AND_ACCESSORY_SHOPS
ART_DEALERS_GALLERIES
ART_DESIGN_AND_PHOTOGRAPHY
BAR_CLUB_LOUNGE
BEAUTY_AND_BARBER_SHOPS
BOOK_STORES
BUSINESS_SERVICES
CATERING
CHARITABLE_SOCIAL_SERVICE_ORGANIZATIONS
CHARITIBLE_ORGS
CLEANING_SERVICES
COMPUTER_EQUIPMENT_SOFTWARE_MAINTENANCE_REPAIR_SERVICES
CONSULTANT
CONTRACTORS
DELIVERY_SERVICES
DENTISTRY
EDUCATION
FOOD_STORES_CONVENIENCE_STORES_AND_SPECIALTY_MARKETS
FOOD_TRUCK_CART
FURNITURE_HOME_AND_OFFICE_EQUIPMENT
FURNITURE_HOME_GOODS
HOTELS_AND_LODGING
INDIVIDUAL_USE
JEWELRY_AND_WATCHES
LANDSCAPING_AND_HORTICULTURAL_SERVICES
LANGUAGE_SCHOOLS
LEGAL_SERVICES
MEDICAL_PRACTITIONERS
MEDICAL_SERVICES_AND_HEALTH_PRACTITIONERS
MEMBERSHIP_ORGANIZATIONS
MUSIC_AND_ENTERTAINMENT
OTHER
OUTDOOR_MARKETS
PERSONAL_SERVICES
POLITICAL_ORGANIZATIONS
PROFESSIONAL_SERVICES
REAL_ESTATE
RECREATION_SERVICES
REPAIR_SHOPS_AND_RELATED_SERVICES
RESTAURANTS
RETAIL_SHOPS
SCHOOLS_AND_EDUCATIONAL_SERVICES
SPORTING_GOODS
TAXICABS_AND_LIMOUSINES
TICKET_SALES
TOURISM
TRAVEL_TOURISM
VETERINARY_SERVICES
WEB_DEV_DESIGN

V1ModifierListSelectionType

Fields

Name Description
SINGLE
MULTIPLE

V1PageCellObjectType

Fields

Name Description
ITEM
DISCOUNT
CATEGORY
PLACEHOLDER

V1PageCellPlaceholderType

Fields

Name Description
ALL_ITEMS
DISCOUNTS_CATEGORY
REWARDS_FINDER

V1PaymentItemizationItemizationType

Fields

Name Description
ITEM
CUSTOM_AMOUNT
GIFT_CARD_ACTIVATION
GIFT_CARD_RELOAD
GIFT_CARD_UNKNOWN
OTHER

V1PaymentSurchargeType

Fields

Name Description
UNKNOWN
AUTO_GRATUITY
CUSTOM

V1PaymentTaxInclusionType

Fields

Name Description
ADDITIVE
INCLUSIVE

V1RefundType

Fields

Name Description
FULL
PARTIAL

V1SettlementEntryType

Fields

Name Description
ADJUSTMENT

A manual adjustment applied to the merchant's account by Square

BALANCE_CHARGE

A payment from an existing Square balance, such as a gift card

CHARGE

A credit card payment CAPTURE

FREE_PROCESSING

Square offers Free Payments Processing for a variety of business scenarios including seller referral or when we want to apologize for a bug, customer service, repricing complication, etc. This entry represents a credit to the merchant for the purposes of Free Processing.

HOLD_ADJUSTMENT

An adjustment made by Square related to holding/releasing a payment

PAID_SERVICE_FEE

a fee paid to a 3rd party merchant

PAID_SERVICE_FEE_REFUND

a refund for a 3rd party merchant fee

REDEMPTION_CODE

Repayment for a redemption code

REFUND

A refund for an existing card payment

RETURNED_PAYOUT

An entry created when we receive a response for the ACH file we sent indicating that the settlement of the original entry failed.

SQUARE_CAPITAL_ADVANCE

Initial deposit to a merchant for a Capital merchant cash advance (MCA).

SQUARE_CAPITAL_PAYMENT

Capital merchant cash advance (MCA) assessment. These are, generally, proportional to the merchant's sales but may be issued for other reasons related to the MCA.

SQUARE_CAPITAL_REVERSED_PAYMENT

Capital merchant cash advance (MCA) assessment refund. These are, generally, proportional to the merchant's refunds but may be issued for other reasons related to the MCA.

SUBSCRIPTION_FEE

Fee charged for subscription to a Square product

SUBSCRIPTION_FEE_REFUND

Refund of a previously charged Square product subscription fee.

OTHER
INCENTED_PAYMENT

A payment in which Square covers part of the funds for a purchase

RETURNED_ACH_ENTRY

A settlement failed to be processed and the settlement amount has been returned to the account

RETURNED_SQUARE_275

Refund for cancelling a Square Plus subscription

SQUARE_275

Fee charged for a Square Plus subscription ($275)

SQUARE_CARD

Settlements to or withdrawals from the Square Card (an asset)

V1SettlementStatus

Fields

Name Description
FAILED
SENT

V1TenderCardBrand

The brand of a credit card.

Fields

Name Description
OTHER_BRAND
VISA
MASTER_CARD
AMERICAN_EXPRESS
DISCOVER
DISCOVER_DINERS
JCB
CHINA_UNIONPAY
SQUARE_GIFT_CARD

V1TenderEntryMethod

Fields

Name Description
MANUAL
SCANNED
SQUARE_CASH
SQUARE_WALLET
SWIPED
WEB_FORM
OTHER

V1TenderType

Fields

Name Description
CREDIT_CARD
CASH
THIRD_PARTY_CARD
NO_SALE
SQUARE_WALLET
SQUARE_GIFT_CARD
UNKNOWN
OTHER

V1TimecardEventEventType

Actions that resulted in a change to a timecard. All timecard events created with the Connect API have an event type that begins with API.

Fields

Name Description
API_CREATE

The timecard was created by a request to the CreateTimecard endpoint.

API_EDIT

The timecard was edited by a request to the UpdateTimecard endpoint.

API_DELETE

The timecard was deleted by a request to the DeleteTimecard 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.

V1UpdateModifierListRequestSelectionType

Fields

Name Description
SINGLE
MULTIPLE

V1VariationInventoryAlertType

Fields

Name Description
LOW_QUANTITY
NONE
INVESTMENT
LOAN
SAVINGS
OTHER

V1VariationPricingType

Fields

Name Description
FIXED_PRICING
VARIABLE_PRICING

Weekday

The days of the week.

Fields

Name Description
MON

Monday

TUE

Tuesday

WED

Wednesday

THU

Thursday

FRI

Friday

SAT

Saturday

SUN

Sunday

Connect API Appendix

V1Webhooks API

Webhooks (also known as web callbacks or push APIs) are HTTP calls or snippets of code that are triggered by specific events.

See the Webhooks API guide for more information.

Available webhook events

Different webhook events require different permissions. Applications must have the required permission scope to subscribe to webhook events. Subscribing to, or updating subscriptions for, webhook events without the necessary permissions fails with an error.

If permission for a given event is revoked at a later time, it will not generate an error, but the application no longer receives notifications for that event type.

Webhook event Description Perimssion required
PAYMENT_UPDATED A charge was made or refunded through Square Point of Sale or the Transaction API. PAYMENTS_READ
INVENTORY_UPDATED The inventory quantity for a catalog item was updated. ITEMS_READ
TIMECARD_UPDATED A timecard was created in the Square dashboard or an employee clocked in using Square Point of Sale. TIMECARDS_READ

ListWebhooks

GET /v1/{location_id}/webhooks

Lists which types of events trigger webhook notifications for a particular location. See the Webhooks API guide for more information.

Path Parameters

Name event Type Description
location_id string The ID of the location to list webhook notification types for.

Return Value

A list of webhook event enums.

UpdateWebhooks

PUT /v1/{location_id}/webhooks

Changes the webhook event subscriptions for a location. See the Webhooks API guide for more information.

Path Parameters

Name event Type Description
location_id string The ID of the location to list webhook notification types for.

Return Value

A list of webhook event enums the location is currently subscribed to.

V1Batching

V1SubmitBatch

POST /v1/batch

V1SubmitBatch lets you bundle multiple requests to Connect V1 API endpoints as a single request. V1SubmitBatch responds with an array that contains response objects for each of batched requests.

The V1SubmitBatch endpoint does not require an access token in the request header. Instead, provide an access_token parameter for each request included in the batch.

Request Parameters

Name event 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.

BatchResponse

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

Name Type Description
status_code number HTTP status code for the response
headers object Contains any important headers for the response, indexed by header name. For example, if the response includes a pagination header, the header value is available from `headers["Link"]`.
body object The body of the response (if any).
request_id string The value provided in the request for `request_id` in the corresponding `BatchRequest` (if any).

Working with dates

All Connect APIs represent dates as strings in ISO 8601 format and dates returned by the Connect API are always UTC.

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

Endpoints that accept an optional date range with begin_time and end_time parameters also accept an optional order parameter, which indicates whether results are returned in chronological (ASC) or reverse-chronological (DESC) order. For chronological ordering, begin_time is inclusive and end_time is exclusive. For reverse-chronological ordering, begin_time is exclusive and end_time is inclusive.