Connect API Technical Reference

Square-Version: 2019-08-14 Technical Reference Archive
Try our Beta API Technical Reference >
New!

Try our newly redesigned Technical Reference

Try new design

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.

Webhook Events

The type of an event that triggers a webhook notification to an application.

inventory.count.updated

The quantity was updated for a catalog item variation. Webhook notification data is packaged as: InventoryCount[].

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, CatalogImages 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
standard_unit_description_group StandardUnitDescriptionGroup

Names and abbreviations for standard units.

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.

Important: ListCatalog does not return deleted catalog items. To retrieve deleted catalog items, use SearchCatalogObjects and set include_deleted_objects to true.

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, CatalogImages 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, CatalogImages 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": "merchant+support@website.com",
  "pre_populate_buyer_email": "example@email.com",
  "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": "merchant+support@website.com",
    "pre_populate_buyer_email": "example@email.com",
    "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": "Amelia.Earhart@example.com",
  "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": "Amelia.Earhart@example.com",
    "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 Square ID of the customer profile the card is linked 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 full name printed on the credit card.

verification_token string

An identifying token generated by SqPaymentForm.verifyBuyer(). Verification tokens encapsulate customer device information and 3-D Secure challenge results to indicate that Square has verified the buyer identity.

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": "Amelia.Earhart@example.com",
      "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": "Amelia.Earhart@example.com",
    "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": "james.bond@example.com",
      "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": "amelia.earhart@example.com",
      "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": "New.Amelia.Earhart@example.com",
  "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": "New.Amelia.Earhart@example.com",
    "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.

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": "057P5VYJ4A5X1",
      "reference_id": "my-order-001",
      "line_items": [
        {
          "uid": "945986d1-9586-11e6-ad5a-28cfe92138cf",
          "name": "Awesome product",
          "quantity": "1",
          "base_price_money": {
            "amount": 1599,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1599,
            "currency": "USD"
          }
        },
        {
          "uid": "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 a new Order which can include information on products for purchase and settings to apply to the purchase.

To pay for a created order, please refer to the Pay for Orders guide.

You can modify open orders using the UpdateOrder endpoint.

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

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",
  "order": {
    "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"
        }
      }
    ],
    "taxes": [
      {
        "name": "State Sales Tax",
        "type": "ADDITIVE",
        "percentage": "9",
        "applied_money": {
          "amount": 510,
          "currency": "USD"
        },
        "scope": "ORDER"
      }
    ],
    "discounts": [
      {
        "catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7",
        "name": "Membership Discount",
        "type": "FIXED_PERCENTAGE",
        "percentage": "0.5",
        "applied_money": {
          "amount": 30,
          "currency": "USD"
        },
        "scope": "ORDER"
      },
      {
        "name": "Labor Day Sale",
        "type": "FIXED_PERCENTAGE",
        "percentage": "5",
        "applied_money": {
          "amount": 303,
          "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"
      }
    ],
    "total_money": {
      "amount": 6176,
      "currency": "USD"
    },
    "total_tax_money": {
      "amount": 510,
      "currency": "USD"
    },
    "total_discount_money": {
      "amount": 433,
      "currency": "USD"
    }
  }
}

PayOrder BETA

POST /v2/orders/{order_id}/pay

Pay for an order using one or more approved payments, or settle an order with a total of 0.

The total of the payment_ids listed in the request must be equal to the order total. Orders with a total amount of 0 can be marked as paid by specifying an empty array of payment_ids in the request.

To be used with PayOrder, a payment must:

  • Reference the order by specifying the order_id when creating the payment. Any approved payments that reference the same order_id not specified in the payment_ids will be canceled.
  • Be approved with delayed capture. Using a delayed capture payment with PayOrder will complete the approved payment.

Learn how to pay for orders with a single payment using the Payments API.

Required permissions: PAYMENTS_WRITE ORDERS_WRITE

Path Parameters

Name Type Description
order_id
(required)
string

The ID of the order being paid.

Body Parameters

Name Type Description
idempotency_key
(required)
string

A value you specify that uniquely identifies this request among requests you've sent. If you're unsure whether a particular payment request was completed successfully, you can reattempt it with the same idempotency key without worrying about duplicate payments.

See Idempotency for more information.

order_version integer

The version of the order being paid. If not supplied, the latest version will be paid.

payment_ids string[]

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

order Order

The paid, updated order.

Example Request

POST /v2/orders/{order_id}/pay

{
  "idempotency_key": "c043a359-7ad9-4136-82a9-c3f1d66dcbff",
  "payment_ids": [
    "EnZdNAlWCmfh6Mt5FMNST1o7taB",
    "0LRiVlbXVwe8ozu4KbZxd12mvaB"
  ]
}

Example Response

{
  "order": {
    "id": "lgwOlEityYPJtcuvKTVKT1pA986YY",
    "location_id": "P3CCK6HSNDAS7",
    "line_items": [
      {
        "uid": "QW6kofLHJK7JEKMjlSVP5C",
        "quantity": "1",
        "name": "Item 1",
        "base_price_money": {
          "amount": 500,
          "currency": "USD"
        },
        "gross_sales_money": {
          "amount": 500,
          "currency": "USD"
        },
        "total_tax_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_discount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_money": {
          "amount": 500,
          "currency": "USD"
        }
      },
      {
        "uid": "zhw8MNfRGdFQMI2WE1UBJD",
        "quantity": "2",
        "name": "Item 2",
        "base_price_money": {
          "amount": 750,
          "currency": "USD"
        },
        "gross_sales_money": {
          "amount": 1500,
          "currency": "USD"
        },
        "total_tax_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_discount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_money": {
          "amount": 1500,
          "currency": "USD"
        }
      }
    ],
    "created_at": "2019-08-06T02:47:35.693Z",
    "updated_at": "2019-08-06T02:47:37.140Z",
    "version": 4,
    "total_tax_money": {
      "amount": 0,
      "currency": "USD"
    },
    "total_discount_money": {
      "amount": 0,
      "currency": "USD"
    },
    "total_money": {
      "amount": 2000,
      "currency": "USD"
    },
    "closed_at": "2019-08-06T02:47:37.140Z",
    "tenders": [
      {
        "id": "EnZdNAlWCmfh6Mt5FMNST1o7taB",
        "location_id": "P3CCK6HSNDAS7",
        "transaction_id": "lgwOlEityYPJtcuvKTVKT1pA986YY",
        "created_at": "2019-08-06T02:47:36.293Z",
        "amount_money": {
          "amount": 1000,
          "currency": "USD"
        },
        "type": "CARD",
        "card_details": {
          "status": "CAPTURED",
          "card": {
            "card_brand": "VISA",
            "last_4": "1111",
            "exp_month": 2,
            "exp_year": 2022,
            "fingerprint": "sq-1-n_BL15KP87ClDa4-h2nXOI0fp5VnxNH6hfhzqhptTfAgxgLuGFcg6jIPngDz4IkkTQ"
          },
          "entry_method": "KEYED"
        },
        "payment_id": "EnZdNAlWCmfh6Mt5FMNST1o7taB"
      },
      {
        "id": "0LRiVlbXVwe8ozu4KbZxd12mvaB",
        "location_id": "P3CCK6HSNDAS7",
        "transaction_id": "lgwOlEityYPJtcuvKTVKT1pA986YY",
        "created_at": "2019-08-06T02:47:36.809Z",
        "amount_money": {
          "amount": 1000,
          "currency": "USD"
        },
        "type": "CARD",
        "card_details": {
          "status": "CAPTURED",
          "card": {
            "card_brand": "VISA",
            "last_4": "1111",
            "exp_month": 2,
            "exp_year": 2022,
            "fingerprint": "sq-1-n_BL15KP87ClDa4-h2nXOI0fp5VnxNH6hfhzqhptTfAgxgLuGFcg6jIPngDz4IkkTQ"
          },
          "entry_method": "KEYED"
        },
        "payment_id": "0LRiVlbXVwe8ozu4KbZxd12mvaB"
      }
    ],
    "total_service_charge_money": {
      "amount": 0,
      "currency": "USD"
    },
    "net_amounts": {
      "total_money": {
        "amount": 2000,
        "currency": "USD"
      },
      "tax_money": {
        "amount": 0,
        "currency": "USD"
      },
      "discount_money": {
        "amount": 0,
        "currency": "USD"
      },
      "tip_money": {
        "amount": 0,
        "currency": "USD"
      },
      "service_charge_money": {
        "amount": 0,
        "currency": "USD"
      }
    },
    "source": {
      "name": "Source Name"
    },
    "state": "COMPLETED"
  }
}

SearchOrders

POST /v2/orders/search

Search all orders for one or more locations. Orders include all sales, returns, and exchanges regardless of how or when they entered the Square Ecosystem (e.g. Point of Sale, Invoices, Connect APIs, etc).

SearchOrders requests need to specify which locations to search and define a SearchOrdersQuery object which controls how to sort or filter the results. Your SearchOrdersQuery can:

Set filter criteria. Set sort order. Determine whether to return results as complete Order objects, or as OrderEntry objects.

Note that details for orders processed with Square Point of Sale while in offline mode may not be transmitted to Square for up to 72 hours. Offline orders have a created_at value that reflects the time the order was created, not the time it was subsequently transmitted to Square.

Required permissions: ORDERS_READ

Body Parameters

Name Type Description
location_ids string[]

The location IDs for the orders to query. All locations must belong to the same merchant.

Min: 1 location IDs.

Max: 10 location IDs.

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.

query SearchOrdersQuery

Query conditions used to filter or sort the results. Note that when fetching additional pages using a cursor, the query must be equal to the query used to fetch the first page of results.

limit integer

Maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page.

Default: 500

return_entries boolean

Boolean that controls the format of the search results. If true, SearchOrders will return OrderEntry objects. If false, SearchOrders will return complete Order objects.

Default: false.

Response fields

Name Type Description
order_entries OrderEntry[]

List of OrderEntries that fit the query conditions. Populated only if return_entries was set to true in the request.

orders Order[]

List of Order objects that match query conditions. Populated only if return_entries in the request is set to false.

cursor string

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

errors Error[]

Errors encountered during the search.

Example Request

POST /v2/orders/search

{
  "return_entries": true,
  "limit": 3,
  "location_ids": [
    "057P5VYJ4A5X1",
    "18YC4JDH91E1H"
  ],
  "query": {
    "filter": {
      "date_time_filter": {
        "closed_at": {
          "start_at": "2018-03-03T20:00:00+00:00",
          "end_at": "2019-03-04T21:54:45+00:00"
        }
      },
      "state_filter": {
        "states": [
          "COMPLETED"
        ]
      }
    },
    "sort": {
      "sort_field": "CLOSED_AT",
      "sort_order": "DESC"
    }
  }
}

Example Response

{
  "order_entries": [
    {
      "order_id": "CAISEM82RcpmcFBM0TfOyiHV3es",
      "location_id": "057P5VYJ4A5X1",
      "version": 1
    },
    {
      "order_id": "CAISENgvlJ6jLWAzERDzjyHVybY",
      "location_id": "18YC4JDH91E1H"
    },
    {
      "order_id": "CAISEM52YcpmcWAzERDOyiWS3ty",
      "location_id": "057P5VYJ4A5X1"
    }
  ],
  "cursor": "123"
}

UpdateOrder BETA

PUT /v2/locations/{location_id}/orders/{order_id}

Updates an open Order by adding, replacing, or deleting fields. Orders with a COMPLETED or CANCELED state cannot be updated.

An UpdateOrder request requires the following:

  • The order_id in the endpoint path, identifying the order to update.
  • The latest version of the order to update.
  • The sparse order containing only the fields to update and the version the update is being applied to.
  • If deleting fields, the dot notation paths identifying fields to clear.

To pay for an order, please refer to the Pay for Orders guide.

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 order's associated location.

order_id
(required)
string

The ID of the order to update.

Body Parameters

Name Type Description
order Order

The sparse order containing only the fields to update and the version the update is being applied to.

fields_to_clear string[]

The dot notation paths fields to clear. For example, line_items[uid].note Read more about Deleting fields.

idempotency_key string

A value you specify that uniquely identifies this update request

If you're unsure whether a particular update was applied to an order successfully, you can reattempt it with the same idempotency key without worrying about creating duplicate updates to the order. The latest order version will be returned.

See Idempotency for more information.

Response fields

Name Type Description
order Order

The updated Order.

errors Error[]

Any errors that occurred during the request.

Example Request

PUT /v2/locations/{location_id}/orders/{order_id}

{
  "idempotency_key": "UNIQUE_STRING",
  "order": {
    "version": 1,
    "line_items": [
      {
        "uid": "cookie_uid",
        "quantity": "2",
        "name": "COOKIE",
        "base_price_money": {
          "amount": 200,
          "currency": "USD"
        }
      }
    ]
  },
  "fields_to_clear": [
    "discounts"
  ]
}

Example Response

{
  "order": {
    "version": 2,
    "total_money": {
      "currency": "USD",
      "amount": 900
    },
    "source": {
      "name": "Cookies"
    },
    "line_items": [
      {
        "total_tax_money": {
          "currency": "USD",
          "amount": 0
        },
        "total_money": {
          "amount": 500,
          "currency": "USD"
        },
        "gross_sales_money": {
          "amount": 500,
          "currency": "USD"
        },
        "base_price_money": {
          "amount": 500,
          "currency": "USD"
        },
        "quantity": "1",
        "total_discount_money": {
          "currency": "USD",
          "amount": 0
        },
        "name": "Small Coffee",
        "uid": "EuYkakhmu3ksHIds5Hiot",
        "variation_total_price_money": {
          "amount": 500,
          "currency": "USD"
        }
      },
      {
        "total_money": {
          "amount": 400,
          "currency": "USD"
        },
        "gross_sales_money": {
          "currency": "USD",
          "amount": 400
        },
        "total_tax_money": {
          "currency": "USD",
          "amount": 0
        },
        "variation_total_price_money": {
          "currency": "USD",
          "amount": 400
        },
        "name": "COOKIE",
        "uid": "cookie_uid",
        "base_price_money": {
          "amount": 200,
          "currency": "USD"
        },
        "quantity": "2",
        "total_discount_money": {
          "amount": 0,
          "currency": "USD"
        }
      }
    ],
    "state": "OPEN",
    "total_service_charge_money": {
      "amount": 0,
      "currency": "USD"
    },
    "id": "DREk7wJcyXNHqULq8JJ2iPAsluJZY",
    "location_id": "MXVQSVNDGN3C8",
    "total_tax_money": {
      "amount": 0,
      "currency": "USD"
    },
    "created_at": "2019-08-23T18:26:18.243Z",
    "total_discount_money": {
      "amount": 0,
      "currency": "USD"
    },
    "net_amounts": {
      "service_charge_money": {
        "currency": "USD",
        "amount": 0
      },
      "total_money": {
        "amount": 900,
        "currency": "USD"
      },
      "discount_money": {
        "currency": "USD",
        "amount": 0
      },
      "tax_money": {
        "currency": "USD",
        "amount": 0
      }
    },
    "updated_at": "2019-08-23T18:33:47.523Z"
  }
}

CancelPayment

POST /v2/payments/{payment_id}/cancel

Cancels (voids) a payment. If you set autocomplete to false when creating a payment, you can cancel the payment using this endpoint. For more information, see Delayed Payments.

Required permissions: PAYMENTS_WRITE

Path Parameters

Name Type Description
payment_id
(required)
string

payment_id identifying the payment to be canceled.

Response fields

Name Type Description
errors Error[]

Information on errors encountered during the request.

payment Payment

The successfully canceled Payment object.

Example Request

POST /v2/payments/{payment_id}/cancel

Example Response

{
  "payment": {
    "id": "YNR82sYrdgYlEEvJHnkJ7jrRuaB",
    "created_at": "2018-10-17T20:38:46.743Z",
    "updated_at": "2018-10-17T20:38:57.693Z",
    "amount_money": {
      "amount": 200,
      "currency": "USD"
    },
    "app_fee_money": {
      "amount": 10,
      "currency": "USD"
    },
    "total_money": {
      "amount": 200,
      "currency": "USD"
    },
    "status": "CANCELED",
    "source_type": "CARD",
    "card_details": {
      "status": "VOIDED",
      "card": {
        "card_brand": "VISA",
        "last_4": "1234",
        "exp_month": 2,
        "exp_year": 2024,
        "fingerprint": "sq-1-9PP0tWfcM6vIsYmfsesdjfhduHSDFNdJFNDfDNFjdfjpseirDErsaP"
      },
      "entry_method": "KEYED",
      "cvv_status": "CVV_ACCEPTED",
      "avs_status": "AVS_ACCEPTED",
      "auth_result_code": "eWZBDh"
    },
    "reference_id": "12323232323"
  }
}

CancelPaymentByIdempotencyKey

POST /v2/payments/cancel

Cancels (voids) a payment identified by the idempotency key that is specified in the request.

Use this method when status of a CreatePayment request is unknown. For example, after you send a CreatePayment request a network error occurs and you don't get a response. In this case, you can direct Square to cancel the payment using this endpoint. In the request, you provide the same idempotency key that you provided in your CreatePayment request you want to cancel. After cancelling the payment, you can submit your CreatePayment request again. Note that if no payment with the specified idempotency key is found, no action is taken, the end point returns successfully.

Required permissions: PAYMENTS_WRITE

Body Parameters

Name Type Description
idempotency_key
(required)
string

idempotency_key identifying the payment to be canceled.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

Example Request

POST /v2/payments/cancel

{
  "idempotency_key": "a7e36d40-d24b-11e8-b568-0800200c9a66"
}

CompletePayment

POST /v2/payments/{payment_id}/complete

Completes (captures) a payment.

By default, payments are set to complete immediately after they are created. If you set autocomplete to false when creating a payment, you can complete (capture) the payment using this endpoint. For more information, see Delayed Payments.

Required permissions: PAYMENTS_WRITE

Path Parameters

Name Type Description
payment_id
(required)
string

Unique ID identifying the payment to be completed.

Response fields

Name Type Description
errors Error[]

Information on errors encountered during the request

payment Payment

The successfully completed Payment.

Example Request

POST /v2/payments/{payment_id}/complete

Example Response

{
  "payment": {
    "id": "EdMl5lwmBxd3ZvsvinkAT5LtvaB",
    "created_at": "2019-07-10T13:39:55.317Z",
    "updated_at": "2019-07-10T13:40:05.982Z",
    "amount_money": {
      "amount": 200,
      "currency": "USD"
    },
    "app_fee_money": {
      "amount": 10,
      "currency": "USD"
    },
    "total_money": {
      "amount": 200,
      "currency": "USD"
    },
    "status": "COMPLETED",
    "source_type": "CARD",
    "card_details": {
      "status": "CAPTURED",
      "card": {
        "card_brand": "VISA",
        "last_4": "2796",
        "exp_month": 7,
        "exp_year": 2026,
        "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw"
      },
      "entry_method": "ON_FILE",
      "cvv_status": "CVV_ACCEPTED",
      "avs_status": "AVS_ACCEPTED",
      "auth_result_code": "MhIjEN"
    },
    "location_id": "XK3DBG77NJBFX",
    "order_id": "iJbzEHMhcwydeLbN3Apg5ZAjGi4F",
    "reference_id": "123456",
    "note": "Brief description",
    "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8"
  }
}

CreatePayment

POST /v2/payments

Charges a payment source, for example, a card represented by customer's card on file or a card nonce. In addition to the payment source, the request must also include the amount to accept for the payment.

There are several optional parameters that you can include in the request. For example, tip money, whether to autocomplete the payment, or a reference ID to correlate this payment with another system. For more information about these payment options, see Take Payments.

The PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission is required to enable application fees.

Required permissions: PAYMENTS_WRITE

Body Parameters

Name Type Description
source_id
(required)
string

The ID for the source of funds for this payment. This can be a nonce generated by the Payment Form or a card on file made with the Customers API.

idempotency_key
(required)
string

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

Max: 45 characters

See Idempotency keys for more information.

amount_money
(required)
Money

The amount of money to accept for this payment, not including tip_money.

Must be specified 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 currency code must match the currency associated with the business that is accepting the payment.

tip_money BETA Money

The amount designated as a tip, in addition to amount_money

Must be specified 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 currency code must match the currency associated with the business that is accepting the payment.

app_fee_money Money

The amount of money the developer is taking as a fee for facilitating the payment on behalf of the seller.

Cannot be more than 90% of the total amount of the Payment.

Must be specified 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 currency code must match the currency associated with the business that is accepting the payment.

For more information about the application fee scenario, see Collect Fees.

autocomplete boolean

If set to true, this payment will be completed when possible. If set to false, this payment will be held in an approved state until either explicitly completed (captured) or canceled (voided). For more information, see Delayed Payments.

Default: true

order_id string

Associate a previously created order with this payment

customer_id string

The ID of the customer associated with the payment. Required if the source_id refers to a card on file created using the Customers API.

location_id string

The location ID to associate with the payment. If not specified, the default location is used.

reference_id string

A user-defined ID to associate with the payment. You can use this field to associate the payment to an entity in an external system. For example, you might specify an order ID that is generated by a third-party shopping cart.

Limit 40 characters.

verification_token string

An identifying token generated by SqPaymentForm.verifyBuyer(). Verification tokens encapsulate customer device information and 3-D Secure challenge results to indicate that Square has verified the buyer identity.

See the SCA Overview for more.

accept_partial_authorization BETA boolean

If set to true and charging a Square Gift Card, a payment may be returned with amount_money equal to less than what was requested. Example, a request for $20 when charging a Square Gift Card with balance of $5 wil result in an APPROVED payment of $5. You may choose to prompt the buyer for an additional payment to cover the remainder, or cancel the gift card payment. Cannot be true when `autocomplete = true

For more information, see Partial amount with Square gift cards.

Default: false

buyer_email_address string

The buyer's e-mail address

billing_address Address

The buyer's billing address.

shipping_address Address

The buyer's shipping address.

note string

An optional note to be entered by the developer when creating a payment

Limit 500 characters.

Response fields

Name Type Description
errors Error[]

Information on errors encountered during the request.

payment Payment

The newly created payment.

Example Request

POST /v2/payments

{
  "idempotency_key": "4935a656-a929-4792-b97c-8848be85c27c",
  "amount_money": {
    "amount": 200,
    "currency": "USD"
  },
  "source_id": "ccof:uIbfJXhXETSP197M3GB",
  "autocomplete": true,
  "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8",
  "location_id": "XK3DBG77NJBFX",
  "reference_id": "123456",
  "note": "Brief description",
  "app_fee_money": {
    "amount": 10,
    "currency": "USD"
  }
}

Example Response

{
  "payment": {
    "id": "iqrBxAil6rmDtr7cak9g9WO8uaB",
    "created_at": "2019-07-10T13:23:49.154Z",
    "updated_at": "2019-07-10T13:23:49.446Z",
    "amount_money": {
      "amount": 200,
      "currency": "USD"
    },
    "app_fee_money": {
      "amount": 10,
      "currency": "USD"
    },
    "total_money": {
      "amount": 200,
      "currency": "USD"
    },
    "status": "COMPLETED",
    "source_type": "CARD",
    "card_details": {
      "status": "CAPTURED",
      "card": {
        "card_brand": "VISA",
        "last_4": "2796",
        "exp_month": 7,
        "exp_year": 2026,
        "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw"
      },
      "entry_method": "ON_FILE",
      "cvv_status": "CVV_ACCEPTED",
      "avs_status": "AVS_ACCEPTED",
      "auth_result_code": "nsAyY2"
    },
    "location_id": "XK3DBG77NJBFX",
    "order_id": "qHkNOb03hMgEgoP3gyzFBDY3cg4F",
    "reference_id": "123456",
    "note": "Brief description",
    "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8"
  }
}

GetPayment

GET /v2/payments/{payment_id}

Retrieves details for a specific Payment.

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
payment_id
(required)
string

Unique ID for the desired Payment.

Response fields

Name Type Description
errors Error[]

Information on errors encountered during the request.

payment Payment

The requested Payment.

Example Request

GET /v2/payments/{payment_id}

Example Response

{
  "payment": {
    "id": "iqrBxAil6rmDtr7cak9g9WO8uaB",
    "created_at": "2019-07-10T13:23:49.154Z",
    "updated_at": "2019-07-10T13:23:49.446Z",
    "amount_money": {
      "amount": 200,
      "currency": "USD"
    },
    "app_fee_money": {
      "amount": 10,
      "currency": "USD"
    },
    "total_money": {
      "amount": 200,
      "currency": "USD"
    },
    "status": "COMPLETED",
    "source_type": "CARD",
    "card_details": {
      "status": "CAPTURED",
      "card": {
        "card_brand": "VISA",
        "last_4": "2796",
        "exp_month": 7,
        "exp_year": 2026,
        "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw"
      },
      "entry_method": "ON_FILE",
      "cvv_status": "CVV_ACCEPTED",
      "avs_status": "AVS_ACCEPTED",
      "auth_result_code": "nsAyY2"
    },
    "location_id": "XK3DBG77NJBFX",
    "order_id": "qHkNOb03hMgEgoP3gyzFBDY3cg4F",
    "reference_id": "123456",
    "note": "Brief description",
    "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8",
    "processing_fee": [
      {
        "effective_at": "2019-07-10T15:23:49.000Z",
        "type": "INITIAL",
        "amount_money": {
          "amount": 36,
          "currency": "USD"
        }
      }
    ]
  }
}

ListPayments

GET /v2/payments

Retrieves a list of payments taken by the account making the request.

Max results per page: 100

Required permissions: PAYMENTS_READ

Query Parameters

Name Type Description
begin_time string

Timestamp for the beginning of the reporting period, in RFC 3339 format. Inclusive. Default: The current time minus one year.

end_time string

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

Default: The current time.

sort_order string

The order in which results are listed.

  • ASC - oldest to newest
  • DESC - newest to oldest (default).
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.

location_id string

ID of location associated with payment

total integer

The exact amount in the total_money for a Payment.

last_4 string

The last 4 digits of Payment card.

card_brand string

The brand of Payment card. For example, VISA

Response fields

Name Type Description
errors Error[]

Information on errors encountered during the request.

payments Payment[]

The requested list of Payments.

cursor string

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

See Pagination for more information.

Example Request

GET /v2/payments

Example Response

{
  "payments": [
    {
      "id": "6SRrImjQGn8FuzIsURiN677CwaB",
      "created_at": "2019-07-09T14:36:13.745Z",
      "updated_at": "2019-07-09T14:36:13.883Z",
      "amount_money": {
        "amount": 1000,
        "currency": "USD"
      },
      "total_money": {
        "amount": 1000,
        "currency": "USD"
      },
      "status": "APPROVED",
      "source_type": "CARD",
      "card_details": {
        "status": "AUTHORIZED",
        "card": {
          "card_brand": "VISA",
          "last_4": "1111",
          "exp_month": 2,
          "exp_year": 2022,
          "fingerprint": "sq-1-lHpUJIUyqOPQmH89b6GuQEljmc-mZmu4kSTaMlkLDkJI7NVjAl4Zirn2sk3OeyVKVA"
        },
        "entry_method": "KEYED",
        "cvv_status": "CVV_ACCEPTED",
        "avs_status": "AVS_ACCEPTED",
        "auth_result_code": "NQbV3A"
      },
      "location_id": "XK3DBG77NJBFX",
      "order_id": "EM6qWxDd7RSy5udzjXktPw3PJa4F"
    },
    {
      "id": "MRWmTKxBDNRgwfNSZptAO76xuaB",
      "created_at": "2019-07-08T01:00:51.607Z",
      "updated_at": "2019-07-08T01:13:58.508Z",
      "amount_money": {
        "amount": 1000,
        "currency": "USD"
      },
      "total_money": {
        "amount": 1000,
        "currency": "USD"
      },
      "status": "COMPLETED",
      "source_type": "CARD",
      "card_details": {
        "status": "CAPTURED",
        "card": {
          "card_brand": "VISA",
          "last_4": "2796",
          "exp_month": 7,
          "exp_year": 2026,
          "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw"
        },
        "entry_method": "ON_FILE",
        "cvv_status": "CVV_ACCEPTED",
        "avs_status": "AVS_ACCEPTED",
        "auth_result_code": "vPIr0K"
      },
      "location_id": "XK3DBG77NJBFX",
      "order_id": "OVE4bJyb4B6bGFwMYEtVdfE4ge4F",
      "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8",
      "processing_fee": [
        {
          "effective_at": "2019-07-08T03:00:53.000Z",
          "type": "INITIAL",
          "amount_money": {
            "amount": 59,
            "currency": "USD"
          }
        }
      ]
    }
  ],
  "cursor": "Q2g4SUF4SWJUVkpYYlZSTGVFSkVUbEpuZDJaT1UxcHdkRUZQTnpaNGRXRkNFSmVJNVBpOExRPT0"
}

GetPaymentRefund

GET /v2/refunds/{refund_id}

Retrieves a specific Refund using the refund_id.

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
refund_id
(required)
string

Unique ID for the desired PaymentRefund.

Response fields

Name Type Description
errors Error[]

Information on errors encountered during the request.

refund PaymentRefund

The requested PaymentRefund.

Example Request

GET /v2/refunds/{refund_id}

Example Response

{
  "refund": {
    "id": "O2QAAhTYs7rUfzlxT38GMO7LvaB_q7JwCHtxmgXrh8fAhV468WQ44VxDtL7CU4yVRlsbXmI",
    "created_at": "2019-07-06T18:01:22.123Z",
    "updated_at": "2019-07-06T18:06:03.874Z",
    "status": "COMPLETED",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "payment_id": "O2QAAhTYs7rUfzlxT38GMO7LvaB",
    "order_id": "2duiyoqbfeXY0DBi15GEyk5Epa4F",
    "location_id": "XK3DBG77NJBFX",
    "processing_fee": [
      {
        "effective_at": "2019-07-06T20:01:12.000Z",
        "type": "INITIAL",
        "amount_money": {
          "amount": -59,
          "currency": "USD"
        }
      }
    ]
  }
}

ListPaymentRefunds

GET /v2/refunds

Retrieves a list of refunds for the account making the request.

Max results per page: 100

Required permissions: PAYMENTS_READ

Query Parameters

Name Type Description
begin_time string

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

Default: The current time minus one year.

end_time string

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

Default: The current time.

sort_order string

The order in which results are listed.

  • ASC - oldest to newest
  • DESC - newest to oldest (default).
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.

location_id string

ID of location associated with payment.

status string

If provided, only refunds with the given status are returned. For a list of refund status values, see PaymentRefund.

Default: If omitted refunds are returned regardless of status.

source_type string

If provided, only refunds with the given source type are returned.

  • CARD - List refunds only for payments where card was specified as payment source.

Default: If omitted refunds are returned regardless of source type.

Response fields

Name Type Description
errors Error[]

Information on errors encountered during the request.

refunds PaymentRefund[]

The list of requested refunds.

cursor string

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

See Pagination for more information.

Example Request

GET /v2/refunds

Example Response

{
  "refunds": [
    {
      "id": "O2QAAhTYs7rUfzlxT38GMO7LvaB_q7JwCHtxmgXrh8fAhV468WQ44VxDtL7CU4yVRlsbXmI",
      "created_at": "2019-07-06T18:01:22.335Z",
      "updated_at": "2019-07-06T18:06:04.653Z",
      "status": "COMPLETED",
      "amount_money": {
        "amount": 1000,
        "currency": "USD"
      },
      "payment_id": "O2QAAhTYs7rUfzlxT38GMO7LvaB",
      "order_id": "2duiyoqbfeXY0DBi15GEyk5Epa4F",
      "location_id": "XK3DBG77NJBFX",
      "processing_fee": [
        {
          "effective_at": "2019-07-06T20:01:12.000Z",
          "type": "INITIAL",
          "amount_money": {
            "amount": -59,
            "currency": "USD"
          }
        }
      ]
    },
    {
      "id": "8TDIQvFw8PeDIxhSfd5yyX7GuaB_13px5Vrz01qzzuoGzmjsZIxDjfHhbkm2XppBUX1dW7I",
      "created_at": "2019-07-06T17:01:54.232Z",
      "updated_at": "2019-07-06T17:21:04.684Z",
      "status": "COMPLETED",
      "amount_money": {
        "amount": 1000,
        "currency": "USD"
      },
      "payment_id": "8TDIQvFw8PeDIxhSfd5yyX7GuaB",
      "order_id": "w6EXfEwS03oTQsnZTCqfE6f67e4F",
      "processing_fee": [
        {
          "effective_at": "2019-07-06T19:01:45.000Z",
          "type": "INITIAL",
          "amount_money": {
            "amount": -59,
            "currency": "USD"
          }
        }
      ],
      "location_id": "XK3DBG77NJBFX"
    }
  ],
  "cursor": "5evquW1YswHoT4EoyUhzMmTsCnsSXBU9U0WJ4FU4623nrMQcocH0RGU6Up1YkwfiMcF59ood58EBTEGgzMTGHQJpocic7ExOL0NtrTXCeWcv0UJIJNk8eXb"
}

RefundPayment

POST /v2/refunds

Refunds a payment. You can refund the entire payment amount or a portion of it. For more information, see Payments and Refunds Overview.

Required permissions: PAYMENTS_WRITE

Body Parameters

Name Type Description
idempotency_key
(required)
string

A unique string that identifies this RefundPayment request. Key can be any valid string but must be unique for every RefundPayment request. For more information, see Idempotency keys.

amount_money
(required)
Money

The amount of money to refund.

Cannot be more than the total_money value of the payment minus the total amount of all previously completed refunds for this payment.

Must be specified 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 currency code must match the currency associated with the business that is charging the card.

app_fee_money BETA Money

Amount of money the developer will contribute to help cover the refunded amount. Specified in the smallest denomination of the applicable currency. For example, US dollar amounts are specified in cents.

Value cannot be more than the amount_money.

You can specify this parameter in a refund request only if the same parameter was also included when taking the payment. This is part of the application fee scenario the API supports. For more information, see Collect Fees

payment_id string

Unique ID of the payment being refunded.

reason string

A description of the reason for the refund.

Response fields

Name Type Description
errors Error[]

Information on errors encountered during the request.

refund PaymentRefund

The successfully created PaymentRefund.

Example Request

POST /v2/refunds

{
  "idempotency_key": "a7e36d40-d24b-11e8-b568-0800200c9a66",
  "payment_id": "UNOE3kv2BZwqHlJ830RCt5YCuaB",
  "amount_money": {
    "amount": 100,
    "currency": "USD"
  }
}

Example Response

{
  "refund": {
    "id": "UNOE3kv2BZwqHlJ830RCt5YCuaB_xVteEWVFkXDvKN1ddidfJWipt8p9whmElKT5mZtJ7wZ",
    "status": "PENDING",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "payment_id": "UNOE3kv2BZwqHlJ830RCt5YCuaB",
    "created_at": "2018-10-17T20:41:55.520Z",
    "updated_at": "2018-10-17T20:41:55.520Z"
  }
}

ListAdditionalRecipientReceivableRefunds DEPRECATED

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 DEPRECATED

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 DEPRECATED

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 the Delay Capture of Funds recipe 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 DEPRECATED

POST /v2/locations/{location_id}/transactions

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

Deprecated - recommend using CreatePayment

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.

verification_token string

An identifying token generated by SqPaymentForm.verifyBuyer(). Verification tokens encapsulate customer device information and 3-D Secure challenge results to indicate that Square has verified the buyer identity.

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 DEPRECATED

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

Initiates a refund for a previously charged tender.

Deprecated - recommend using RefundPayment

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 DEPRECATED

GET /v2/locations/{location_id}/refunds

Lists refunds for one of a business's locations.

Deprecated - recommend using SearchOrders

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 DEPRECATED

GET /v2/locations/{location_id}/transactions

Lists transactions for a particular location.

Deprecated - recommend using SearchOrders

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 DEPRECATED

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

Retrieves details for a single transaction.

Deprecated - recommend using BatchRetrieveOrders

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 DEPRECATED

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 the Delay Capture of Funds recipe 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

A description of the cash drawer shift.

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 V1ModifierList[]

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 V1ModifierList[]

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 V1ModifierList[]

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 V1ModifierList[]

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 V1ModifierList[]

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 V1ModifierList[]

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 V1ModifierList[]

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 V1ModifierList[]

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 V1ModifierList[]

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 V1ModifierList[]

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

Example Request

GET /v1/{location_id}/payments

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 DEPRECATED

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 DEPRECATED

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.

BalancePaymentDetails

Reflects the current status of a balance payment.

Fields

Name Type Description
account_id string

ID for the account used to fund the payment.

status string

The balance payment’s current state. Can be COMPLETED or FAILED.

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.

BusinessHours

Represents the hours of operation for a business location.

Fields

Name Type Description
periods BusinessHoursPeriod[]

The list of time periods during which the business is open. There may be at most 10 periods per day.

BusinessHoursPeriod

Represents a period of time during which a business location is open.

Fields

Name Type Description
day_of_week string

The day of week for this time period. See DayOfWeek for possible values

start_local_time string

The start time of a business hours period, specified in local time using partial-time RFC3339 format.

end_local_time string

The end time of a business hours period, specified in local time using partial-time RFC3339 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

A unique, Square-assigned ID that identifies the card across multiple locations and applications for a single Square account.

CardPaymentDetails

Reflects the current status of a card payment.

Fields

Name Type Description
status string

The card payment's current state. It can be one of: AUTHORIZED, CAPTURED, VOIDED, FAILED.

card Card

The credit card's non-confidential details.

entry_method string

The method used to enter the card's details for the payment. Can be KEYED, SWIPED, EMV, ON_FILE, or CONTACTLESS.

cvv_status string

Status code returned from the Card Verification Value (CVV) check. Can be CVV_ACCEPTED, CVV_REJECTED, CVV_NOT_CHECKED.

avs_status string

Status code returned from the Address Verification System (AVS) check. Can be AVS_ACCEPTED, AVS_REJECTED, AVS_NOT_CHECKED.

auth_result_code string

Status code returned by the card issuer that describes the payment's authorization status.

application_identifier string

For EMV payments, identifies the EMV application used for the payment.

application_name string

For EMV payments, the human-readable name of the EMV application used for the payment.

application_cryptogram string

For EMV payments, the cryptogram generated for the payment.

errors Error[]

Information on errors encountered during the request.

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.

Maximum: 250 item variations

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 or APPOINTMENTS_SERVICE 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.

item_options BETA CatalogItemOptionForItem[]

List of item options IDs for this item. Used to manage and group item variations in a specified order.

Maximum: 6 item options.

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.

CatalogItemOption BETA

A group of variations for a CatalogItem's.

Fields

Name Type Description
name string

The item option's display name for the seller. Must be unique across all item options. Searchable.

display_name string

The item option's display name for the customer. Searchable.

description string

The item option's human-readable description. Displays for in the Square Point of Sale app for the seller and in the Online Store or on receipts for the buyer.

show_colors boolean

If true, display colors for entries in values when present.

values CatalogObject[]

A list of CatalogObjects containing the CatalogItemOptionValues for this item.

item_count integer

The number of CatalogItems currently associated with this item option. Present only if the include_counts was specified in the request. Any count over 100 will be returned as 100.

CatalogItemOptionForItem BETA

A list of item option values that can be assigned to item variations. For example, a t-shirt item may offer a color option or a size option.

Fields

Name Type Description
item_option_id string

The unique id of the item option, used to form the dimensions of the item option matrix in a specified order.

CatalogItemOptionValue BETA

An enumerated value that can link a [CatalogItemVariation(#type-catalogitemvariation) to an item option as one of its item option values.

Fields

Name Type Description
item_option_id string

Unique ID of the associated item option.

name string

Name of this item option value. Searchable.

description string

The option value's human-readable description.

color string

The HTML color for this value in the format #FFRRGGBB or #RRGGBB (e.g., "#ff8d4e85"). Only displayed if parent Item Option's show_colors flag is enabled. value.

ordinal integer

Determines where this option value appears in a list of option values.

item_variation_count integer

The number of [CatalogItemVariation(#type-catalogitemvariation)s that currently make use of this Item Option value. Present only if retrieve_counts was specified on the request used to retrieve the parent Item Option of this value.

Maximum: 100 counts.

CatalogItemOptionValueForItemVariation BETA

A CatalogItemOptionValue links an item variation to an item option as an item option value. For example, a t-shirt item may offer a color option and a size option. An item option value would represent each variation of t-shirt: For example, “Color:Red, Size:Small” or “Color:Blue, Size:Medium”.

Fields

Name Type Description
item_option_id string

The unique id of an item option.

item_option_value_id string

The unique id of the selected value for the item option.

CatalogItemVariation

An item variation (i.e., product) in the Catalog object model. Each item may have a maximum of 250 item variations.

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

item_option_values BETA CatalogItemOptionValueForItemVariation[]

List of item option values associated with this item variation. Listed in the same order as the item options of the parent item.

measurement_unit_id BETA string

ID of the ‘CatalogMeasurementUnit’ that is used to measure the quantity sold of this item variation. If left unset, the item will be sold in whole quantities.

CatalogMeasurementUnit BETA

Represents the unit used to measure a CatalogItemVariation and specifies the precision for decimal quantities.

Fields

Name Type Description
measurement_unit MeasurementUnit

Indicates the unit used to measure the quantity of a catalog item variation.

precision integer

Represents the maximum number of positions allowed after the decimal in quantities measured with this unit. For example, if the precision is 2, then an itemization’s quantity can be 0.01, 0.12, etc.

Min: 0

Max: 5

Default: 3

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 Design a Catalog guide.

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.

time_period_data BETA CatalogTimePeriod

Structured data for a CatalogTimePeriod, set for CatalogObjects of type TIME_PERIOD.

product_set_data BETA CatalogProductSet

Structured data for a CatalogProductSet, set for CatalogObjects of type PRODUCT_SET.

pricing_rule_data BETA CatalogPricingRule

Structured data for a CatalogPricingRule, set for CatalogObjects of type PRICING_RULE.

image_data CatalogImage

Structured data for a CatalogImage, set for CatalogObjects of type IMAGE.

measurement_unit_data BETA CatalogMeasurementUnit

Structured data for a CatalogMeasurementUnit, set for CatalogObjects of type MEASUREMENT_UNIT.

item_option_data BETA CatalogItemOption

Structured data for a CatalogItemOption, set for CatalogObjects of type ITEM_OPTION.

item_option_value_data BETA CatalogItemOptionValue

Structured data for a CatalogItemOptionValue, set for CatalogObjects of type ITEM_OPTION_VAL.

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.

CatalogPricingRule BETA

Defines how prices are modified or set for items that match the pricing rule during the active time period.

Fields

Name Type Description
name string

User-defined name for the pricing rule. For example, "Buy one get one free" or "10% off".

time_period_ids string[]

Unique ID for the CatalogTimePeriods when this pricing rule is in effect. If left unset, the pricing rule is always in effect.

discount_id string

Unique ID for the CatalogDiscount to take off the price of all matched items.

match_products_id string

Unique ID for the CatalogProductSet that will be matched by this rule. A match rule matches within the entire cart.

apply_products_id string

The CatalogProductSet to apply the pricing rule to within the set of matched products specified by match_products_id. An apply rule can only match once within the set of matched products. If left unset, the pricing rule will be applied to all products within the set of matched products.

exclude_products_id string

Identifies the CatalogProductSet to exclude from this pricing rule. An exclude rule matches within the subset of the cart that fits the match rules (the match set). An exclude rule can only match once in the match set. If not supplied, the pricing will be applied to all products in the match set. Other products retain their base price, or a price generated by other rules.

valid_from_date string

Represents the date the Pricing Rule is valid from. Represented in RFC3339 full-date format (YYYY-MM-DD).

valid_from_local_time string

Represents the local time the pricing rule should be valid from. Time zone is determined by the device running the Point of Sale app.

Represented in RFC3339 partial-time format (HH:MM:SS). Partial seconds will be truncated.

valid_until_date string

Represents the date the pricing rule will become inactive.

Represented in RFC3339 full-date format (YYYY-MM-DD).

valid_until_local_time string

Represents the local time at which the pricing rule will become inactive. Time zone is determined by the device running the Point of Sale app.

Represented in RFC3339 partial-time format (HH:MM:SS). Partial seconds will be truncated.

CatalogProductSet BETA

Represents a collection of catalog objects for the purpose of applying a PricingRule. Including a catalog object will include all of its subtypes. For example, including a category in a product set will include all of its items and associated item variations in the product set. Including an item in a product set will also include its item variations.

Fields

Name Type Description
name string

User-defined name for the product set. For example, "Clearance Items" or "Winter Sale Items".

product_ids_any string[]

Unique IDs for any CatalogObjectss to include in this product set. Any number of these catalog objects can be in an order for a pricing rule to apply.

This can be used with product_ids_all in a parent CatalogProductSet to match groups of products for a bulk discount, such as a discount for an entree and side combo.

Only one of product_ids_all, product_ids_any, or all_products can be set.

Max: 500 catalog object IDs.

product_ids_all string[]

Unique IDs for CatalogObjects to include in this product set. All objects in this set must be included in an order for a pricing rule to apply.

Only one of product_ids_all, product_ids_any, or all_products can be set.

Max: 500 catalog object IDs.

quantity_exact integer

If set, there must be exactly this many items from products_any or products_all in the cart for the discount to apply.

Cannot be combined with either quantity_min or quantity_max.

quantity_min integer

If set, there must be at least this many items from products_any or products_all in a cart for the discount to apply. See quantity_exact. Defaults to 0 if quantity_exact, quantity_min and quantity_max are all unspecified.

quantity_max integer

If set, the pricing rule will apply to a maximum of this many items from products_any or products_all.

all_products boolean

If set to true, the product set will include every item in the catalog.

Only one of product_ids_all, product_ids_any, or all_products can be set.

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.

items_for_item_options_query BETA CatalogQueryItemsForItemOptions

A query that returns all CatalogItems that have all of the given CatalogItemOptions.

item_variations_for_item_option_values_query BETA CatalogQueryItemVariationsForItemOptionValues

A query that returns all CatalogItemVariations that have all of the given CatalogItemOption values.

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.

CatalogQueryItemVariationsForItemOptionValues BETA

Fields

Name Type Description
item_option_value_ids string[]

A set of CatalogItemOptionValue IDs to be used to find associated CatalogItemVariations. All ItemVariations that contain all of the given Item Option Values (in any order) will be returned.

CatalogQueryItemsForItemOptions BETA

Fields

Name Type Description
item_option_ids string[]

A set of CatalogItemOption IDs to be used to find associated CatalogItems. All Items that contain all of the given Item Options (in any order) will be returned.

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

CatalogTimePeriod BETA

Represents a time period - either a single period or a repeating period.

Fields

Name Type Description
event string

An iCalendar (RFC5545) event, which specifies the name, timing, duration and recurrence of this time period.

Example:

DTSTART:20190707T180000
DURATION:P2H
RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR

Only SUMMARY, DTSTART, DURATION and RRULE fields are supported. DTSTART must be in local (unzoned) time format. Note that while BEGIN:VEVENT and END:VEVENT is not required in the request. The response will always include them.

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 DEPRECATED

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.

Coordinates

Latitude and longitude coordinates.

Fields

Name Type Description
latitude number

The coordinate's latitude expressed in degrees.

longitude number

The coordinate's longitude expressed in degrees.

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",
    "order": {
      "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. 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 high-level category for the error. See ErrorCategory for possible values

code string

The specific code of the error. 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 (if any) that the error pertains to.

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

The number of items affected by the adjustment as a decimal string. Can support up to 5 digits after the decimal point.

Important: The Point of Sale app and Dashboard do not currently support decimal quantities. If a Point of Sale app or Dashboard attempts to read a decimal quantity on inventory counts or adjustments, the quantity will be rounded down to the nearest integer. For example, 2.5 will become 2, and -2.5 will become -3.

Read Decimal Quantities (BETA) for more information.

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 Square's 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 BETA string

The number of items in the count as a decimal string. Can support up to 5 digits after the decimal point.

Important: The Point of Sale app and Dashboard do not currently support decimal quantities. If a Point of Sale app or Dashboard attempts to read a decimal quantity on inventory counts or adjustments, the quantity will be rounded down to the nearest integer. For example, 2.5 will become 2, and -2.5 will become -3.

Read Decimal Quantities (BETA) for more information.

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 the quantity of an item variation that is physically present at a specific location, verified by a seller or a seller's employee. For example, a physical count might come from an employee counting the item variations on hand or from syncing with an external system.

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

The number of items affected by the physical count as a decimal string. Can support up to 5 digits after the decimal point.

Important: The Point of Sale app and Dashboard do not currently support decimal quantities. If a Point of Sale app or Dashboard attempts to read a decimal quantity on inventory counts or adjustments, the quantity will be rounded down to the nearest integer. For example, 2.5 will become 2, and -2.5 will become -3.

Read Decimal Quantities (BETA) for more information.

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

The number of items affected by the transfer as a decimal string. Can support up to 5 digits after the decimal point.

Important: The Point of Sale app and Dashboard do not currently support decimal quantities. If a Point of Sale app or Dashboard attempts to read a decimal quantity on inventory counts or adjustments, the quantity will be rounded down to the nearest integer. For example, 2.5 will become 2, and -2.5 will become -3.

Read Decimal Quantities (BETA) for more information.

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