Connect v2 Technical Reference

Square-Version: 2018-12-12 Technical Reference Archive

API Endpoints

RegisterDomain

POST /v2/apple-pay/domains

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

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

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

Body Parameters

Name Type Description
domain_name
(required)
string

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

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

status string

Status of the domain registration.

See RegisterDomainResponseStatus for possible values.

Example Request

POST /v2/apple-pay/domains

{
  "domain_name": "example.com"
}

Example Response

{
  "status": "VERIFIED"
}

BatchDeleteCatalogObjects

POST /v2/catalog/batch-delete

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

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

Required permissions: ITEMS_WRITE

Body Parameters

Name Type Description
object_ids string[]

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

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

deleted_object_ids string[]

The IDs of all CatalogObjects deleted by this request.

deleted_at string

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

Example Request

POST /v2/catalog/batch-delete

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

Example Response

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

BatchRetrieveCatalogObjects

POST /v2/catalog/batch-retrieve

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

Required permissions: ITEMS_READ

Body Parameters

Name Type Description
object_ids
(required)
string[]

The IDs of the CatalogObjects to be retrieved.

include_related_objects boolean

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

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

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

objects CatalogObject[]

A list of CatalogObjects returned.

related_objects CatalogObject[]

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

Example Request

POST /v2/catalog/batch-retrieve

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

Example Response

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

BatchUpsertCatalogObjects

POST /v2/catalog/batch-upsert

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

Required permissions: ITEMS_WRITE

Body Parameters

Name Type Description
idempotency_key
(required)
string

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

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

See Idempotency keys for more information.

batches CatalogObjectBatch[]

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

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

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

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

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

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

objects CatalogObject[]

The created CatalogObjects

updated_at string

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

id_mappings CatalogIdMapping[]

The mapping between client and server IDs for this Upsert.

Example Request

POST /v2/catalog/batch-upsert

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

Example Response

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

CatalogInfo

GET /v2/catalog/info

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

Required permissions: ITEMS_READ

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

limits CatalogInfoResponseLimits

Example Request

GET /v2/catalog/info

Example Response

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

DeleteCatalogObject

DELETE /v2/catalog/object/{object_id}

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

Required permissions: ITEMS_WRITE

Path Parameters

Name Type Description
object_id
(required)
string

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

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

deleted_object_ids string[]

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

deleted_at string

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

Example Request

DELETE /v2/catalog/object/{object_id}

Example Response

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

ListCatalog

GET /v2/catalog/list

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

Required permissions: ITEMS_READ

Query Parameters

Name Type Description
cursor string

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

types string

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

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

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 Paginating results for more information.

objects CatalogObject[]

The CatalogObjects returned.

Example Request

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

Example Response

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

RetrieveCatalogObject

GET /v2/catalog/object/{object_id}

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

Required permissions: ITEMS_READ

Path Parameters

Name Type Description
object_id
(required)
string

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

Query Parameters

Name Type Description
include_related_objects boolean

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

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

Default value: false

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

object CatalogObject

The CatalogObjects returned.

related_objects CatalogObject[]

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

Example Request

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

Example Response

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

SearchCatalogObjects

POST /v2/catalog/search

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

Required permissions: ITEMS_READ

Body Parameters

Name Type Description
cursor string

The pagination cursor returned in the previous response. Leave unset for an initial request. See Paginating results 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".

include_deleted_objects boolean

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

include_related_objects boolean

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

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

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

begin_time string

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

query CatalogQuery

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

limit integer

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

Response fields

Name Type Description
errors Error[]

The set of Errors encountered.

cursor string

The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Paginating results 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 keys for more information.

object
(required)
CatalogObject

A CatalogObject to be created or updated. The object's is_deleted field must not be set to true. When creating a new object, the object's ID must either start with a # character or be left blank. In either case it will be 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

Creates a Checkout response that links a checkoutId and checkout_page_url that customers can 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 keys 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.

Required permissions: CUSTOMERS_WRITE

Path Parameters

Name Type Description
customer_id
(required)
string

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

Body Parameters

Name Type Description
card_nonce
(required)
string

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

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

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

billing_address Address

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

cardholder_name string

The cardholder's name.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

card Card

The created card on file.

Example Request

POST /v2/customers/{customer_id}/cards

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

Example Response

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

DeleteCustomer

DELETE /v2/customers/{customer_id}

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

Required permissions: CUSTOMERS_WRITE

Path Parameters

Name Type Description
customer_id
(required)
string

The ID of the customer to delete.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

Example Request

DELETE /v2/customers/{customer_id}

DeleteCustomerCard

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

Removes a card on file from a customer.

Required permissions: CUSTOMERS_WRITE

Path Parameters

Name Type Description
customer_id
(required)
string

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

card_id
(required)
string

The ID of the card on file to delete.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

Example Request

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

ListCustomers

GET /v2/customers

Lists a business's customers.

Required permissions: CUSTOMERS_READ

Query Parameters

Name Type Description
cursor string

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

See Paginating results for more information.

sort_field string

Indicates how Customers should be sorted. Default: DEFAULT. See CustomerSortField for possible values.

sort_order string

Indicates whether Customers should be sorted in ascending (ASC) or descending (DESC) order. Default: ASC. See SortOrder for possible values.

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 Paginating results 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 Paginating results 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 Paginating results 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"
      }
    ]
  }
}

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.

states string[]

Filters ADJUSTMENT query results by InventoryState. Only applied when set. Default: unset.

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 Paginating results 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 Paginating results 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 Paginating results 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 Paginating results 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_cost_money": {
      "amount": 3500,
      "currency": "USD"
    },
    "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 Paginating results 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 Paginating results 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_cost_money": {
          "amount": 3000,
          "currency": "USD"
        },
        "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 Paginating results 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 Paginating results 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"
  }
}

ListLocations

GET /v2/locations

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

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

Required permissions: MERCHANT_PROFILE_READ

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

locations Location[]

The business's locations.

Example Request

GET /v2/locations

Example Response

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

BatchRetrieveOrders

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

Retrieves a set of Orders by their IDs.

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

Required permissions: ORDERS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the orders' associated location.

Body Parameters

Name Type Description
order_ids
(required)
string[]

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

Response fields

Name Type Description
orders Order[]

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

errors Error[]

Any errors that occurred during the request.

Example Request

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

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

Example Response

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

CreateOrder

POST /v2/locations/{location_id}/orders

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

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

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

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

Required permissions: ORDERS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

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

Body Parameters

Name Type Description
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 keys for more information.

reference_id string

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
(required)
CreateOrderRequestLineItem[]

The line items to associate with this order.

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

taxes CreateOrderRequestTax[]

The taxes to include on the order.

discounts CreateOrderRequestDiscount[]

The discounts to include on the order.

Response fields

Name Type Description
order Order

The newly created order.

errors Error[]

Any errors that occurred during the request.

Example Request

POST /v2/locations/{location_id}/orders

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

Example Response

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

ListAdditionalRecipientReceivableRefunds

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

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

Max results per page: 50

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list AdditionalRecipientReceivableRefunds for.

Query Parameters

Name Type Description
begin_time string

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

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time minus one year.

end_time string

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

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time.

sort_order string

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

Default value: DESC

cursor string

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

See Paginating results 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 Paginating results for more information.

Example Request

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

Example Response

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

ListAdditionalRecipientReceivables

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

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

Max results per page: 50

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list AdditionalRecipientReceivables for.

Query Parameters

Name Type Description
begin_time string

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

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time minus one year.

end_time string

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

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time.

sort_order string

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

Default value: DESC

cursor string

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

See Paginating results 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 Paginating results for more information.

Example Request

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

Example Response

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

CaptureTransaction

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

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

See Delayed capture transactions for more information.

Required permissions: PAYMENTS_WRITE

Path Parameters

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

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

Example Request

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

Charge

POST /v2/locations/{location_id}/transactions

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

Your request to this endpoint must include either:

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

In order for an eCommerce payment to potentially qualify for Square chargeback protection, you must provide values for the following parameters in your request:

  • buyer_email_address
  • At least one of billing_address or shipping_address

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 keys 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
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. This value is optional, but this transaction is ineligible for chargeback protection if neither this parameter nor shipping_address is provided.

shipping_address Address

The buyer's shipping address, if available. This value is optional, but this transaction is ineligible for chargeback protection if neither this parameter nor billing_address is provided.

buyer_email_address string

The buyer's email address, if available. This value is optional, but this transaction is ineligible for chargeback protection if it is not provided.

order_id string

The ID of the order to associate with this transaction.

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

additional_recipients AdditionalRecipient[]

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

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

This field requires the PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission.

This field is currently not supported in sandbox.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

transaction Transaction

The created transaction.

Example Request

POST /v2/locations/{location_id}/transactions

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

Example Response

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

CreateRefund

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

Initiates a refund for a previously charged tender.

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

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

Required permissions: PAYMENTS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the original transaction's associated location.

transaction_id
(required)
string

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

Body Parameters

Name Type Description
idempotency_key
(required)
string

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

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

See Idempotency keys for more information.

tender_id
(required)
string

The ID of the tender to refund.

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

reason string

A description of the reason for the refund.

Default value: Refund via API

amount_money
(required)
Money

The amount of money to refund.

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

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

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

refund Refund

The created refund.

Example Request

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

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

Example Response

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

ListRefunds

GET /v2/locations/{location_id}/refunds

Lists refunds for one of a business's locations.

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

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

Max results per page: 50

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list refunds for.

Query Parameters

Name Type Description
begin_time string

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

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time minus one year.

end_time string

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

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time.

sort_order string

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

Default value: DESC

cursor string

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

See Paginating results 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 Paginating results for more information.

Example Request

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

Example Response

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

ListTransactions

GET /v2/locations/{location_id}/transactions

Lists transactions for a particular location.

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

Max results per page: 50

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list transactions for.

Query Parameters

Name Type Description
begin_time string

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

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time minus one year.

end_time string

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

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time.

sort_order string

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

Default value: DESC

cursor string

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

See Paginating results 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 Paginating results for more information.

Example Request

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

Example Response

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

RetrieveTransaction

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

Retrieves details for a single transaction.

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the transaction's associated location.

transaction_id
(required)
string

The ID of the transaction to retrieve.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

transaction Transaction

The requested transaction.

Example Request

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

Example Response

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

VoidTransaction

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

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

See Delayed capture transactions for more information.

Required permissions: PAYMENTS_WRITE

Path Parameters

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

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

Example Request

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

API Data Types

AdditionalRecipient

Represents an additional recipient (other than the merchant) receiving a portion of this tender.

Fields

Name Type Description
location_id string

The location ID for a recipient (other than the merchant) receiving a portion of this tender.

description string

The description of the additional recipient.

amount_money Money

The amount of money distributed to the recipient.

receivable_id string

The unique ID for this AdditionalRecipientReceivable, assigned by the server.

AdditionalRecipientReceivable

Represents a monetary distribution of part of a Transaction's amount for Transactions which included additional recipients. The location of this receivable is that same as the one specified in the AdditionalRecipient.

Fields

Name Type Description
id string

The additional recipient receivable's unique ID, issued by Square payments servers.

transaction_id string

The ID of the transaction that the additional recipient receivable was applied to.

transaction_location_id string

The ID of the location that created the receivable. This is the location ID on the associated transaction.

amount_money Money

The amount of the receivable. This will always be non-negative.

created_at string

The time when the additional recipient receivable was created, in RFC 3339 format.

refunds AdditionalRecipientReceivableRefund[]

Any refunds of the receivable that have been applied.

AdditionalRecipientReceivableRefund

A refund of an AdditionalRecipientReceivable. This includes the ID of the additional recipient receivable associated to this object, as well as a reference to the Refund that created this receivable refund.

Fields

Name Type Description
id string

The receivable refund's unique ID, issued by Square payments servers.

receivable_id string

The ID of the receivable that the refund was applied to.

refund_id string

The ID of the refund that is associated to this receivable refund.

transaction_location_id string

The ID of the location that created the receivable. This is the location ID on the associated transaction.

amount_money Money

The amount of the refund. This will always be non-negative.

created_at string

The time when the refund was created, in RFC 3339 format.

Address

Represents a physical address.

Fields

Name Type Description
address_line_1 string

The first line of the address.

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

address_line_2 string

The second line of the address, if any.

address_line_3 string

The third line of the address, if any.

locality string

The city or town of the address.

sublocality string

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

sublocality_2 string

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

sublocality_3 string

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

administrative_district_level_1 string

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

administrative_district_level_2 string

A civil entity within the address's administrative_district_level_1. In the US, this is the county.

administrative_district_level_3 string

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

postal_code string

The address's postal code.

country string

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

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.

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 all possible values.

last_4 string

The last 4 digits of the card number.

exp_month integer

The expiration month of the associated card as an integer between 1 and 12.

exp_year integer

The four-digit year of the card's expiration date.

cardholder_name string

The name of the cardholder.

billing_address Address

The billing address for this card.

fingerprint string

Not currently set. Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.

CatalogCategory

A category to which an CatalogItem belongs in the Catalog object model.

Fields

Name Type Description
name string

The category's name. Searchable.

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.

discount_type string

Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale. See CatalogDiscountType for all 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.

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.

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.

description string

The item's description. Searchable.

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.

label_color string

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

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.

image_url string

The URL of an image representing this item.

variations CatalogObject[]

A list of CatalogObjects containing the CatalogItemVariations for this item.

product_type string

The product type of the item. May not be changed once an item has been created.

Only items of product type REGULAR may be created by this API; items with other product types are read-only. See CatalogItemProductType for all possible values.

skip_modifier_screen boolean

If false, the Square Point of Sale app will present the CatalogItem's details screen immediately, allowing the merchant to choose CatalogModifiers before adding the item to the cart. This is the default behavior.

If true, the Square Point of Sale app will immediately add the item to the cart with the pre-selected modifiers, and merchants can edit modifiers by drilling down onto the item's details.

Third-party clients are encouraged to implement similar behaviors.

CatalogItem Example

          {
  "object": {
    "type": "ITEM",
    "id": "#Cocoa",
    "present_at_all_locations": true,
    "item_data": {
      "name": "Cocoa",
      "description": "Hot chocolate",
      "abbreviation": "Ch",
      "visibility": "PRIVATE"
    }
  }
}
        

CatalogItemModifierListInfo

Controls the properties of a CatalogModifierList as it applies to this CatalogItem.

Fields

Name Type Description
modifier_list_id string

The ID of the CatalogModifierList controlled by this CatalogModifierListInfo.

modifier_overrides CatalogModifierOverride[]

A set of CatalogModifierOverride objects that override whether a given CatalogModifier is enabled by default.

min_selected_modifiers integer

If zero or larger, the smallest number of CatalogModifiers that must be selected from this CatalogModifierList.

max_selected_modifiers integer

If zero or larger, the largest number of CatalogModifiers that can be selected from this CatalogModifierList.

enabled boolean

If true, enable this CatalogModifierList.

CatalogItemVariation

An item variation (i.e., product) in the Catalog object model.

Fields

Name Type Description
item_id string

The ID of the CatalogItem associated with this item variation. Searchable.

name string

The item variation's name. Searchable.

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

CatalogItemVariation Example

          {
  "object": {
    "type": "ITEM_VARIATION",
    "id": "#Coffee_Regular",
    "present_at_all_locations": true,
    "item_variation_data": {
      "name": "Regular",
      "pricing_type": "FIXED_PRICING",
      "price_money": {
        "amount": 250,
        "currency": "USD"
      }
    }
  }
}
        

CatalogModifier

A modifier in the Catalog object model.

Fields

Name Type Description
name string

The modifier's name. Searchable.

price_money Money

The modifier's price.

CatalogModifier Example

          {
  "object": {
    "type": "MODIFIER",
    "present_at_all_locations": true,
    "item_modifier": {
      "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.

selection_type string

Indicates whether multiple options from the CatalogModifierList can be applied to a single CatalogItem. See CatalogModifierListSelectionType for all 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,
        "item_modifier": {
          "name": "Whole Milk",
          "price_money": {
            "amount": 0,
            "currency": "USD"
          }
        }
      },
      {
        "type": "MODIFIER",
        "present_at_all_locations": true,
        "item_modifier": {
          "name": "Almond Milk",
          "price_money": {
            "amount": 250,
            "currency": "USD"
          }
        }
      },
      {
        "type": "MODIFIER",
        "present_at_all_locations": true,
        "item_modifier": {
          "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.

For a more detailed discussion of the Catalog data model, please see the Catalog Overview.

Fields

Name Type Description
type string

The type of this object. Each object type has expected properties expressed in a structured format within its corresponding *_data field below.

See CatalogObjectType for all 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 by the 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.

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.

CatalogObject Schema

          {
  "catalog_object": {
    "type": "{{ [ITEM | ITEM_VARIATION | MODIFIER | MODIFIER_LIST | CATEGORY | DISCOUNT | TAX] }}",
    "id": "{{ set by Catalog during object creation }}",
    "updated_at": "{{ date & time of most recent update }}",
    "version": "{{ version of the CatalogObject }}",
    "is_deleted": "{{ [true | false] }}",
    "connect_v1_ids": {
      "catalog_v1_id": "{{ itemID from Catalog v1 }}",
      "location_id": "{{ location where v1 ID is used }}"
    },
    "present_at_all_locations": "{{ [true | false] }}",
    "present_at_location_ids": [
      "{{ LOCATIONID-1 }}",
      "{{ LOCATIONID-N }}"
    ],
    "absent_at_location_ids": [
      "{{ LOCATIONID-1 }}",
      "{{ LOCATIONID-N }}"
    ],
    "item_data": "{{ CatalogItem object only if type=ITEM }}",
    "item_variation_data": "{{ CatalogItemVariation object only if type=ITEM_VARIATION }}",
    "modifier_data": "{{ CatalogModifier object only if type=MODIFIER }}",
    "modifier_list_data": "{{ CatalogModifierList object only if type=MODIFIER_LIST }}",
    "category_data": "{{ CatalogCategory object only if type=CATEGORY }}",
    "discount_data": "{{ CatalogDiscount object only if type=DISCOUNT }}",
    "tax_data": "{{ CatalogTax object only if type=TAX }}"
  }
}
        

CatalogObjectBatch

A batch of CatalogObjects.

Fields

Name Type Description
objects CatalogObject[]

A list of CatalogObjects belonging to this batch.

CatalogQuery

A query to be applied to a SearchCatalogObjectsRequest. Only one query field may be present.

Where an attribute name is required, it should be specified as the name of any field marked "searchable" from the structured data types for the desired result object type(s) (CatalogItem, CatalogItemVariation, CatalogCategory, CatalogTax, CatalogDiscount, CatalogModifierList, CatalogModifier).

For example, a query that should return Items may specify attribute names from any of the searchable fields of the CatalogItem data type, namely "name", "description", and "abbreviation".

Fields

Name Type Description
sorted_attribute_query CatalogQuerySortedAttribute

A query that returns all objects, sorted by the given attribute.

exact_query CatalogQueryExact

A query that returns only objects for which the given (string-valued) attribute has the given case-insensitive value.

prefix_query CatalogQueryPrefix

A query that returns only objects for which the given (string-valued) attribute has the given case-insensitive prefix.

range_query CatalogQueryRange

A query that returns only objects for which the given (integer-valued) attribute lies in the given range.

text_query CatalogQueryText

A query that returns only objects whose searchable attributes contain all of the given keywords as prefixes. For example, if a CatalogItem contains attributes {"name": "t-shirt"} and {"description": "Small, Purple"}, it will be matched by the query {"keywords": ["shirt", "sma", "purp"]}.

items_for_tax_query CatalogQueryItemsForTax

A query that returns all CatalogItems that have any of the given CatalogTaxes enabled.

items_for_modifier_list_query CatalogQueryItemsForModifierList

A query that returns all CatalogItems that have any of the given CatalogModifierLists enabled.

CatalogQueryExact

Fields

Name Type Description
attribute_name string

The name of the attribute to be searched.

attribute_value string

The desired value of the search attribute.

CatalogQueryItemsForModifierList

Fields

Name Type Description
modifier_list_ids string[]

A set of CatalogModifierList IDs to be used to find associated CatalogItems.

CatalogQueryItemsForTax

Fields

Name Type Description
tax_ids string[]

A set of CatalogTax IDs to be used to find associated CatalogItems.

CatalogQueryPrefix

Fields

Name Type Description
attribute_name string

The name of the attribute to be searched.

attribute_prefix string

The desired prefix of the search attribute value.

CatalogQueryRange

Fields

Name Type Description
attribute_name string

The name of the attribute to be searched.

attribute_min_value integer

The desired minimum value for the search attribute (inclusive).

attribute_max_value integer

The desired maximum value for the search attribute (inclusive).

CatalogQuerySortedAttribute

Fields

Name Type Description
attribute_name string

The attribute whose value should be used as the sort key.

initial_attribute_value string

The first attribute value to be returned by the query. Ascending sorts will return only objects with this value or greater, while descending sorts will return only objects with this value or less. If unset, start at the beginning (for ascending sorts) or end (for descending sorts).

sort_order string

The desired SortOrder, "ASC" (ascending) or "DESC" (descending).

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.

calculation_phase string

Whether the tax is calculated based on a payment's subtotal or total. See TaxCalculationPhase for all possible values.

inclusion_type string

Whether the tax is ADDITIVE or INCLUSIVE. See TaxInclusionType for all 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
    }
  }
}
        

ChargeRequestAdditionalRecipient

Represents an additional recipient (other than the merchant) entitled to a portion of the tender. Support is currently limited to USD, CAD and GBP currencies

Fields

Name Type Description
location_id string

The location ID for a recipient (other than the merchant) receiving a portion of the tender.

description string

The description of the additional recipient.

amount_money Money

The amount of money distributed to the recipient.

Checkout

Square Checkout lets merchants accept online payments for supported payment types using a checkout workflow hosted on squareup.com.

Fields

Name Type Description
id string

ID generated by Square Checkout when a new checkout is requested.

checkout_page_url string

The URL that the buyer's browser should be redirected to after the checkout is completed.

ask_for_shipping_address boolean

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

Default: false.

merchant_support_email string

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

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

Default: none; only exists if explicitly set.

pre_populate_buyer_email string

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

Default: none; only exists if explicitly set.

pre_populate_shipping_address Address

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

Default: none; only exists if explicitly set.

redirect_url string

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

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

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

order Order

Order to be checked out.

created_at string

The time when the checkout was created, in RFC 3339 format.

additional_recipients AdditionalRecipient[]

Additional recipients (other than the merchant) receiving a portion of this checkout. For example, fees assessed on the purchase by a third party integration.

CreateOrderRequest

Fields

Name Type Description
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 keys for more information.

reference_id string

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

This value cannot exceed 40 characters.

line_items CreateOrderRequestLineItem[]

The line items to associate with this order.

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

taxes CreateOrderRequestTax[]

The taxes to include on the order.

discounts CreateOrderRequestDiscount[]

The discounts to include on the order.

CreateOrderRequest Example

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

CreateOrderRequestDiscount

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

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

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

Represents a tax that can apply to either a single line item or an entire order.

Fields

Name Type Description
catalog_object_id string

Only used for catalog taxes. The catalog object ID of an existing CatalogTax.

Do not provide a value for this field if you provide values in other fields for an ad hoc tax.

name string

Only used for ad hoc taxes. The tax's name.

Do not provide a value for this field if you set catalog_object_id.

type string

Only used for ad hoc taxes. Indicates the calculation method used to apply the line item tax.

Default: ADDITIVE; See OrderLineItemTaxType for possible values.

percentage string

Only used for ad hoc taxes. The percentage of the tax, as a string representation of a decimal number.

A value of 7.25 corresponds to a percentage of 7.25%. This value range between 0.0 up to 100.0

Customer

Represents one of a business's customers, which can have one or more cards on file associated with it.

Fields

Name Type Description
id string

The customer's unique ID.

created_at string

The time when the customer was created, in RFC 3339 format.

updated_at string

The time when the customer was last updated, in RFC 3339 format.

cards Card[]

The payment details of the customer's cards on file.

given_name string

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

family_name string

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

nickname string

The customer's nickname.

company_name string

The name of the customer's company.

email_address string

The customer's email address.

address Address

The customer's physical address.

phone_number string

The customer's phone number.

birthday string

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

reference_id string

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

note string

A note to associate with the customer.

preferences CustomerPreferences

The customer's preferences.

groups CustomerGroupInfo[]

The groups the customer belongs to.

creation_source string

A creation source represents the method used to create the customer profile.

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. Default value: DEFAULT.

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. Default value: ASC.

Device

Fields

Name Type Description
id string

The device's Square-issued ID.

name string

The device's merchant-specified name.

Error

Represents an error encountered during a request to the Connect API.

See Handling errors for more information.

Fields

Name Type Description
category string

The error's high-level category. See ErrorCategory for possible values.

code string

The error's specific code. See ErrorCode for possible values

detail string

A human-readable description of the error for debugging purposes.

field string

The name of the field provided in the original request that the error pertains to, if any.

InventoryAdjustment

Represents a change in state or quantity of product inventory at a particular time and location.

Fields

Name Type Description
id string

A unique ID generated by Square for the InventoryAdjustment.

reference_id string

An optional ID provided by the application to tie the InventoryAdjustment to an external system.

from_state string

The InventoryState of the related quantity of items before the adjustment.

to_state string

The InventoryState of the related quantity of items after the adjustment.

location_id string

The Square ID of the Location where the related quantity of items are being tracked.

catalog_object_id string

The Square generated ID of the CatalogObject being tracked.

catalog_object_type string

The CatalogObjectType of the CatalogObject being tracked. Tracking is only supported for the ITEM_VARIATION type.

quantity string

The number of items affected by the adjustment as a decimal string. Fractional quantities are not supported.

total_price_money Money

The read-only total price paid for goods associated with the adjustment. Present if and only if to_state is SOLD. Always non-negative.

occurred_at string

A client-generated timestamp in RFC 3339 format that indicates when the adjustment took place. For write actions, the occurred_at timestamp cannot be older than 24 hours or in the future relative to the time of the request.

created_at string

A read-only timestamp in RFC 3339 format that indicates when Square received the adjustment.

source SourceApplication

Read-only information about the application that caused the inventory adjustment.

employee_id string

The Square ID of the Employee responsible for the inventory adjustment.

transaction_id string

The read-only Square ID of the [Transaction][#type-transaction] that caused the adjustment. Only relevant for payment-related state transitions.

refund_id string

The read-only Square ID of the [Refund][#type-refund] that caused the adjustment. Only relevant for refund-related state transitions.

purchase_order_id string

The read-only Square ID of the purchase order that caused the adjustment. Only relevant for state transitions from the Square for Retail app.

goods_receipt_id string

The read-only Square ID of the Square goods receipt that caused the adjustment. Only relevant for state transitions from the Square for Retail app.

InventoryChange

Represents a single physical count, inventory, adjustment, or transfer that is part of the history of inventory changes for a particular CatalogObject.

Fields

Name Type Description
type string

Indicates how the inventory change was applied. See InventoryChangeType for all possible values.

physical_count InventoryPhysicalCount

Contains details about the physical count when type is PHYSICAL_COUNT and unset for all other types.

adjustment InventoryAdjustment

Contains details about the inventory adjustment when type is ADJUSTMENT and unset for all other types.

transfer InventoryTransfer

Contains details about the inventory transfer when type is TRANSFER and unset for all other types.

InventoryCount

Represents the estimated quantity of items in a particular state at a particular location based on the known history of physical counts and inventory adjustments.

Fields

Name Type Description
catalog_object_id string

The Square generated ID of the CatalogObject being tracked.

catalog_object_type string

The CatalogObjectType of the CatalogObject being tracked. Tracking is only supported for the ITEM_VARIATION type.

state string

The current InventoryState for the related quantity of items.

location_id string

The Square ID of the Location where the related quantity of items are being tracked.

quantity string

The number of items in the count as a decimal string. Fractional quantities are not supported.

calculated_at string

A read-only timestamp in RFC 3339 format that indicates when Square received the most recent physical count or adjustment that had an affect on the estimated count.

InventoryPhysicalCount

Represents a verified (re)count of items in a given state at a specific location. For example, the quantity of items currently on hand at a physical store).

Fields

Name Type Description
id string

A unique ID generated by Square for the InventoryPhysicalCount.

reference_id string

An optional ID provided by the application to tie the InventoryPhysicalCount to an external system.

catalog_object_id string

The Square generated ID of the CatalogObject being tracked.

catalog_object_type string

The CatalogObjectType of the CatalogObject being tracked. Tracking is only supported for the ITEM_VARIATION type.

state string

The current InventoryState for the related quantity of items.

location_id string

The Square ID of the Location where the related quantity of items are being tracked.

quantity string

The number of items affected by the physical count as a decimal string. Fractional quantities are not supported.

source SourceApplication

Read-only information about the application that submitted the physical count.

employee_id string

The Square ID of the Employee responsible for the physical count.

occurred_at string

A client-generated timestamp in RFC 3339 format that indicates when the physical count took place. For write actions, the occurred_at timestamp cannot be older than 24 hours or in the future relative to the time of the request.

created_at string

A read-only timestamp in RFC 3339 format that indicates when Square received the physical count.

InventoryTransfer

Represents the transfer of a quantity of product inventory at a particular time from one location to another.

Fields

Name Type Description
id string

A unique ID generated by Square for the InventoryTransfer.

reference_id string

An optional ID provided by the application to tie the InventoryTransfer to an external system.

state string

The InventoryState for the quantity of items being transfered.

from_location_id string

The Square ID of the Location where the related quantity of items were tracked before the transfer.

to_location_id string

The Square ID of the Location where the related quantity of items were tracked after the transfer.

catalog_object_id string

The Square generated ID of the CatalogObject being tracked.

catalog_object_type string

The CatalogObjectType of the CatalogObject being tracked.Tracking is only supported for the ITEM_VARIATION type.

quantity string

The number of items affected by the transfer as a decimal string. Fractional quantities are not supported.

occurred_at string

A client-generated timestamp in RFC 3339 format that indicates when the transfer took place. For write actions, the occurred_at timestamp cannot be older than 24 hours or in the future relative to the time of the request.

created_at string

A read-only timestamp in RFC 3339 format that indicates when Square received the transfer request.

source SourceApplication

Read-only information about the application that initiated the inventory transfer.

employee_id string

The Square ID of the Employee responsible for the inventory transfer.

ItemVariationLocationOverrides

Price and inventory alerting overrides for a CatalogItemVariation at a specific location.

Fields

Name Type Description
location_id string

The ID of the location.

price_money Money

The price of the CatalogItemVariation at the given location, or blank for variable pricing.

pricing_type string

The pricing type (fixed or variable) for the CatalogItemVariation at the given location. See CatalogPricingType for all 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 all possible values.

inventory_alert_threshold integer

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

This value is always an integer.

Location

Represents one of a business's locations.

Fields

Name Type Description
id string

The location's unique ID.

name string

The location's name. Location names are set by the account owner and displayed in the dashboard as the location's nickname

address Address

The location's physical address.

timezone string

The IANA Timezone Database identifier for the location's timezone.

capabilities string[]

Indicates which Square features are enabled for the location.

See LocationCapability for possible values.

status string

The location's status

See LocationStatus for possible values.

created_at string

The time when the location was created, in RFC 3339 format.

merchant_id string

The identifier of the merchant that owns the location.

country string

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

See Country for possible values.

language_code string

The language associated with the location in BCP 47 format.

currency string

The currency used for all transactions at this location, specified in ISO 4217 format. For example, the currency for a location processing transactions in the United States is 'USD'.

See Currency for possible values.

phone_number string

The location's phone_number.

business_name string

The location's business_name which is shown to its customers. For example, this is the name printed on its customer's receipts.

type string

The location's type, as set by the account owner in the Square dashboard. Typically used to indicate whether or not the location object represents a physical space like a building or mall space.

See LocationType for possible values.

website_url string

The location's website, as set by the account owner in the Square dashboard.

Default: none; only exists if explicitly set.

Money

Represents an amount of money.

Important: Unlike version 1 of the Connect API, all monetary amounts returned by v2 endpoints are positive. (In v1, monetary amounts are negative if they represent money being paid by a merchant, instead of money being paid to a merchant.)

Fields

Name Type Description
amount integer

The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents.

currency string

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

See Currency for possible values.

Order

Contains all information related to a single order to process with Square, including line items that specify the products to purchase

Fields

Name Type Description
id string

The order's unique ID.

This value is only present for Order objects created by the Orders API through the CreateOrder endpoint.

location_id string

The ID of the merchant location this order is associated with.

reference_id string

A client specified identifier to associate an entity in another system with this order.

line_items OrderLineItem[]

The line items included in the order. Every order has at least one line item.

total_money Money

The total amount of money to collect for the order.

total_tax_money Money

The total tax amount of money to collect for the order.

total_discount_money Money

The total discount amount of money to collect for the order.

OrderLineItem

Represents a line item in an order. Each line item describes a different product to purchase, with its own quantity and price details.

Fields

Name Type Description
name string

The name of the line item.

quantity string

The quantity purchased, as a string representation of a number.

This string must have a positive integer value.

note string

The note of the line item.

catalog_object_id string

The CatalogItemVariation id applied to this line item.

variation_name string

The name of the variation applied to this line item.

modifiers OrderLineItemModifier[]

The CatalogModifiers applied to this line item.

taxes OrderLineItemTax[]

The taxes applied to this line item.

discounts OrderLineItemDiscount[]

The discounts applied to this line item.

base_price_money Money

The base price for a single unit of the line item.

gross_sales_money Money

The gross sales amount of money calculated as (item base price + modifiers price) * quantity.

total_tax_money Money

The total tax amount of money to collect for the line item.

total_discount_money Money

The total discount amount of money to collect for the line item.

total_money Money

The total amount of money to collect for this line item.

OrderLineItemDiscount

Represents a discount that applies to one or more line items in an order.

Fixed-amount, order-level discounts are distributed across all non-zero line item totals. The amount distributed to each line item is relative to that item’s contribution to the order subtotal.

Fields

Name Type Description
catalog_object_id string

The catalog object id referencing CatalogDiscount.

name string

The discount's name.

type string

The type of the discount. If it is created by API, it would be either FIXED_PERCENTAGE or FIXED_AMOUNT.

VARIABLE_* is not supported in API because the order is created at the time of sale and either percentage or amount has to be specified.

See OrderLineItemDiscountType for possible values.

percentage string

The percentage of the tax, as a string representation of a decimal number. A value of 7.25 corresponds to a percentage of 7.25%.

The percentage won't be set for an amount-based discount.

amount_money Money

The total monetary amount of the applicable discount. If it is at order level, it is the value of the order level discount. If it is at line item level, it is the value of the line item level discount.

The amount_money won't be set for a percentage-based discount.

applied_money Money

The amount of discount actually applied to this line item.

Represents the amount of money applied to a line item as a discount When an amount-based discount is at order-level, this value is different from amount_money because the discount is distributed across the line items.

scope string

Indicates the level at which the discount applies. See OrderLineItemDiscountScope for possible values.

OrderLineItemModifier

A CatalogModifier.

Fields

Name Type Description
catalog_object_id string

The catalog object id referencing CatalogModifier.

name string

The name of the item modifier.

base_price_money Money

The base price for the modifier.

base_price_money is required for ad hoc modifiers. If both catalog_object_id and base_price_money are set, base_price_money will override the predefined CatalogModifier price.

total_price_money Money

The total price of the item modifier for its line item. This is the modifier's base_price_money multiplied by the line item's quantity.

OrderLineItemTax

Represents a tax that applies to one or more line items in an order.

Fields

Name Type Description
catalog_object_id string

The catalog object id referencing CatalogTax.

name string

The tax's name.

type string

Indicates the calculation method used to apply the tax.

See OrderLineItemTaxType for possible values.

percentage string

The percentage of the tax, as a string representation of a decimal number.

A value of 7.25 corresponds to a percentage of 7.25%.

applied_money Money

The amount of the money applied by the tax in an order.

Refund

Represents a refund processed for a Square transaction.

Fields

Name Type Description
id string

The refund's unique ID.

location_id string

The ID of the refund's associated location.

transaction_id string

The ID of the transaction that the refunded tender is part of.

tender_id string

The ID of the refunded tender.

created_at string

The time when the refund was created, in RFC 3339 format.

reason string

The reason for the refund being issued.

amount_money Money

The amount of money refunded to the buyer.

status string

The current status of the refund (PENDING, APPROVED, REJECTED, or FAILED).

processing_fee_money Money

The amount of Square processing fee money refunded to the merchant.

additional_recipients AdditionalRecipient[]

Additional recipients (other than the merchant) receiving a portion of this refund. For example, fees assessed on a refund of a purchase by a third party integration.

SourceApplication

Provides information about the application used to generate an inventory change.

Fields

Name Type Description
product string

Read-only Product type for the application.

application_id string

Read-only Square ID assigned to the application. Only used for Product type EXTERNAL_API.

name string

Read-only display name assigned to the application (e.g. "Custom Application", "Square POS 4.74 for Android").

Tender

Represents a tender (i.e., a method of payment) used in a Square transaction.

Fields

Name Type Description
id string

The tender's unique ID.

location_id string

The ID of the transaction's associated location.

transaction_id string

The ID of the tender's associated transaction.

created_at string

The time when the tender was created, in RFC 3339 format.

note string

An optional note associated with the tender at the time of payment.

amount_money Money

The amount of the tender.

tip_money Money

The tip's amount of the tender.

processing_fee_money Money

The amount of any Square processing fees applied to the tender.

This field is not immediately populated when a new transaction is created. It is usually available after about ten seconds.

customer_id string

If the tender is associated with a customer or represents a customer's card on file, this is the ID of the associated customer.

type string

The type of tender, such as CARD or CASH.

card_details TenderCardDetails

The details of the card tender.

This value is present only if the value of type is CARD.

cash_details TenderCashDetails

The details of the cash tender.

This value is present only if the value of type is CASH.

additional_recipients AdditionalRecipient[]

Additional recipients (other than the merchant) receiving a portion of this tender. For example, fees assessed on the purchase by a third party integration.

TenderCardDetails

Represents additional details of a tender with type CARD or SQUARE_GIFT_CARD

Fields

Name Type Description
status string

The credit card payment's current state (such as AUTHORIZED or CAPTURED). See TenderCardDetailsStatus for possible values.

card Card

The credit card's non-confidential details.

entry_method string

The method used to enter the card's details for the transaction.

TenderCashDetails

Represents the details of a tender with type CASH.

Fields

Name Type Description
buyer_tendered_money Money

The total amount of cash provided by the buyer, before change is given.

change_back_money Money

The amount of change returned to the buyer.

TimeRange

Represents a generic time range. The start and end values are represented in RFC-3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevent endpoint-specific documentation to determine how time ranges are handled.

Fields

Name Type Description
start_at string

A datetime value in RFC-3339 format indicating when the time range starts.

end_at string

A datetime value in RFC-3339 format indicating when the time range ends.

Transaction

Represents a transaction processed with Square, either with the Connect API or with Square Point of Sale.

The tenders field of this object lists all methods of payment used to pay in the transaction.

Fields

Name Type Description
id string

The transaction's unique ID, issued by Square payments servers.

location_id string

The ID of the transaction's associated location.

created_at string

The time when the transaction was created, in RFC 3339 format.

tenders Tender[]

The tenders used to pay in the transaction.

refunds Refund[]

Refunds that have been applied to any tender in the transaction.

reference_id string

If the transaction was created with the Charge endpoint, this value is the same as the value provided for the reference_id parameter in the request to that endpoint. Otherwise, it is not set.

product string

The Square product that processed the transaction.

client_id string

If the transaction was created in the Square Point of Sale app, this value is the ID generated for the transaction by Square Point of Sale.

This ID has no relationship to the transaction's canonical id, which is generated by Square's backend servers. This value is generated for bookkeeping purposes, in case the transaction cannot immediately be completed (for example, if the transaction is processed in offline mode).

It is not currently possible with the Connect API to perform a transaction lookup by this value.

shipping_address Address

The shipping address provided in the request, if any.

order_id string

The order_id is an identifier for the order associated with this transaction, if any.

API Enums

CardBrand

Indicates a credit card's brand, such as VISA or MASTERCARD.

Fields

Name Description
OTHER_BRAND
VISA
MASTERCARD
AMERICAN_EXPRESS
DISCOVER
DISCOVER_DINERS
JCB
CHINA_UNIONPAY
SQUARE_GIFT_CARD

CatalogDiscountType

How to apply a CatalogDiscount to a CatalogItem.

Fields

Name Description
FIXED_PERCENTAGE

Apply the discount as a fixed percentage (e.g., 5%) off the item price.

FIXED_AMOUNT

Apply the discount as a fixed amount (e.g., $1.00) off the item price.

VARIABLE_PERCENTAGE

Apply the discount as a variable percentage off the item price. The percentage will be specified at the time of sale.

VARIABLE_AMOUNT

Apply the discount as a variable amount off the item price. The amount will be specified at the time of sale.

CatalogItemProductType

The type of a CatalogItem. Connect V2 only allows the creation of REGULAR items.

Fields

Name Description
REGULAR

An ordinary item.

GIFT_CARD

A Square gift card.

APPOINTMENTS_SERVICE

A service that can be booked using the Square Appointments app.

RETAIL_ITEM

An item associated with the Retail vertical.

RESTAURANT_ITEM

An item associated with the Restaurants vertical.

CatalogModifierListSelectionType

Indicates whether a CatalogModifierList supports multiple selections.

Fields

Name Description
SINGLE

Indicates that a CatalogModifierList allows only a single CatalogModifier to be selected.

MULTIPLE

Indicates that a CatalogModifierList allows multiple CatalogModifier to be selected.

CatalogObjectType

Possible kinds of CatalogObjects returned from the Catalog, each contaning type-specific properties in the *_data field corresponding to the object type.

Fields

Name Description
ITEM

An item, corresponding to CatalogItem. The item-specific data will be stored in the item_data field.

CATEGORY

A category, corresponding to CatalogCategory. The category-specific data will be stored in the category_data field.

ITEM_VARIATION

An item variation, corresponding to CatalogItemVariation. The item variation-specific data will be stored in the item_variation_data field.

TAX

A tax, corresponding to CatalogTax. The tax-specific data will be stored in the tax_data field.

DISCOUNT

A discount, corresponding to CatalogDiscount. The discount-specific data will be stored in the discount_data field.

MODIFIER_LIST

A modifier list, corresponding to CatalogModifierList. The modifier list-specific data will be stored in the modifier_list_data field.

MODIFIER

A modifier, corresponding to CatalogModifier. The modifier-specific data will be stored in the modifier_data field.

CatalogPricingType

Indicates whether the price of a CatalogItemVariation should be entered manually at the time of sale.

Fields

Name Description
FIXED_PRICING

The CatalogItemVariation's price is fixed.

VARIABLE_PRICING

The CatalogItemVariation's price is entered at the time of sale.

Country

Indicates the country associated with another entity, such as a business. Values are in ISO 3166-1-alpha-2 format.

Fields

Name Description
ZZ
AD
AE
AF
AG
AI
AL
AM
AO
AQ
AR
AS
AT
AU
AW
AX
AZ
BA
BB
BD
BE
BF
BG
BH
BI
BJ
BL
BM
BN
BO
BQ
BR
BS
BT
BV
BW
BY
BZ
CA
CC
CD
CF
CG
CH
CI
CK
CL
CM
CN
CO
CR
CU
CV
CW
CX
CY
CZ
DE
DJ
DK
DM
DO
DZ
EC
EE
EG
EH
ER
ES
ET
FI
FJ
FK
FM
FO
FR
GA
GB
GD
GE
GF
GG
GH
GI
GL
GM
GN
GP
GQ
GR
GS
GT
GU
GW
GY
HK
HM
HN
HR
HT
HU
ID
IE
IL
IM
IN
IO
IQ
IR
IS
IT
JE
JM
JO
JP
KE
KG
KH
KI
KM
KN
KP
KR
KW
KY
KZ
LA
LB
LC
LI
LK
LR
LS
LT
LU
LV
LY
MA
MC
MD
ME
MF
MG
MH
MK
ML
MM
MN
MO
MP
MQ
MR
MS
MT
MU
MV
MW
MX
MY
MZ
NA
NC
NE
NF
NG
NI
NL
NO
NP
NR
NU
NZ
OM
PA
PE
PF
PG
PH
PK
PL
PM
PN
PR
PS
PT
PW
PY
QA
RE
RO
RS
RU
RW
SA
SB
SC
SD
SE
SG
SH
SI
SJ
SK
SL
SM
SN
SO
SR
SS
ST
SV
SX
SY
SZ
TC
TD
TF
TG
TH
TJ
TK
TL
TM
TN
TO
TR
TT
TV
TW
TZ
UA
UG
UM
US
UY
UZ
VA
VC
VE
VG
VI
VN
VU
WF
WS
YE
YT
ZA
ZM
ZW

Currency

Indicates the associated currency for an amount of money. Values correspond to ISO 4217.

Fields

Name Description
UNKNOWN_CURRENCY
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
AWG
AZN
BAM
BBD
BDT
BGN
BHD
BIF
BMD
BND
BOB
BOV
BRL
BSD
BTN
BWP
BYR
BZD
CAD
CDF
CHE
CHF
CHW
CLF
CLP
CNY
COP
COU
CRC
CUC
CUP
CVE
CZK
DJF
DKK
DOP
DZD
EGP
ERN
ETB
EUR
FJD
FKP
GBP
GEL
GHS
GIP
GMD
GNF
GTQ
GYD
HKD
HNL
HRK
HTG
HUF
IDR
ILS
INR
IQD
IRR
ISK
JMD
JOD
JPY
KES
KGS
KHR
KMF
KPW
KRW
KWD
KYD
KZT
LAK
LBP
LKR
LRD
LSL
LTL
LVL
LYD
MAD
MDL
MGA
MKD
MMK
MNT
MOP
MRO
MUR
MVR
MWK
MXN
MXV
MYR
MZN
NAD
NGN
NIO
NOK
NPR
NZD
OMR
PAB
PEN
PGK
PHP
PKR
PLN
PYG
QAR
RON
RSD
RUB
RWF
SAR
SBD
SCR
SDG
SEK
SGD
SHP
SLL
SOS
SRD
SSP
STD
SVC
SYP
SZL
THB
TJS
TMT
TND
TOP
TRY
TTD
TWD
TZS
UAH
UGX
USD
USN
USS
UYI
UYU
UZS
VEF
VND
VUV
WST
XAF
XAG
XAU
XBA
XBB
XBC
XBD
XCD
XDR
XOF
XPD
XPF
XPT
XTS
XXX
YER
ZAR
ZMK
ZMW
BTC

CustomerCreationSource

Indicates the method used to create the customer profile.

Fields

Name Description
OTHER

Default creation source. Typically used for backward/future compatibility when the original source of a customer profile is unrecognized. For example, when older clients do not support newer source types.

APPOINTMENTS

Customer profile created automatically when an appointment was scheduled.

COUPON

Customer profile created automatically when a coupon was issued using Square Point of Sale.

DELETION_RECOVERY

Customer profile restored through Square's deletion recovery process.

DIRECTORY

Customer profile created manually through Square Dashboard or Point of Sale application.

EGIFTING

Customer profile created automatically when a gift card was issued using Square Point of Sale. Customer profiles are created for both the purchaser and the recipient of the gift card.

EMAIL_COLLECTION

Customer profile created through Square Point of Sale when signing up for marketing emails during checkout.

FEEDBACK

Customer profile created automatically when providing feedback through a digital receipt.

IMPORT

Customer profile created automatically when importing customer data through Square Dashboard.

INVOICES

Customer profile created automatically during an invoice payment.

LOYALTY

Customer profile created automatically when customers provide a phone number for loyalty reward programs during checkout.

MARKETING

Customer profile created as the result of a campaign managed through Square’s Facebook integration.

MERGE

Customer profile created as the result of explicitly merging multiple customer profiles through the Square Dashboard or Point of Sale application.

ONLINE_STORE

Customer profile created through Square's Online Store solution (legacy service).

INSTANT_PROFILE

Customer profile created automatically as the result of a successful transaction that did not explicitly link to an existing customer profile.

TERMINAL

Customer profile created through Square's Virtual Terminal.

THIRD_PARTY

Customer profile created through a Square API call.

THIRD_PARTY_IMPORT

Customer profile created by a third-party product and imported through an official integration.

UNMERGE_RECOVERY

Customer profile restored through Square's unmerge recovery process.

CustomerInclusionExclusion

Indicates whether customers should be included in, or excluded from, the result set when they match the filtering criteria.

Fields

Name Description
INCLUDE

Customers should be included in the result set when they match the filtering criteria.

EXCLUDE

Customers should be excluded from the result set when they match the filtering criteria.

CustomerSortField

Indicates the sort criteria for a list of Customers.

Fields

Name Description
DEFAULT

Use the default sort. By default, Customers are sorted alphanumerically by concatenating given_name and family_name. If neither name field is set, string comparison is performed using one of the remaining fields in the following order: company_name, email, phone_number.

CREATED_AT

Sort Customers by their creation date (created_at).

ErrorCategory

Indicates which high-level category of error has occurred during a request to the Connect API.

Fields

Name Description
API_ERROR

An error occurred with the Connect API itself.

AUTHENTICATION_ERROR

An authentication error occurred. Most commonly, the request had a missing, malformed, or otherwise invalid Authorization header.

INVALID_REQUEST_ERROR

The request was invalid. Most commonly, a required parameter was missing, or a provided parameter had an invalid value.

RATE_LIMIT_ERROR

Your application reached the Connect API rate limit. Retry your request after a while.

PAYMENT_METHOD_ERROR

An error occurred while processing a payment method. Most commonly, the details of the payment method were invalid (such as a card's CVV or expiration date).

REFUND_ERROR

An error occurred while attempting to process a refund.

ErrorCode

Indicates specific errors that can occur during a request to the Connect API.

Fields

Name Description
INTERNAL_SERVER_ERROR
UNAUTHORIZED
ACCESS_TOKEN_EXPIRED
ACCESS_TOKEN_REVOKED
FORBIDDEN
INSUFFICIENT_SCOPES
APPLICATION_DISABLED
V1_APPLICATION
V1_ACCESS_TOKEN
CARD_PROCESSING_NOT_ENABLED
BAD_REQUEST
MISSING_REQUIRED_PARAMETER
INCORRECT_TYPE
INVALID_TIME
INVALID_TIME_RANGE
INVALID_VALUE
INVALID_CURSOR
UNKNOWN_QUERY_PARAMETER
CONFLICTING_PARAMETERS
EXPECTED_JSON_BODY
INVALID_SORT_ORDER
VALUE_REGEX_MISMATCH
VALUE_TOO_SHORT
VALUE_TOO_LONG
VALUE_TOO_LOW
VALUE_TOO_HIGH
VALUE_EMPTY
ARRAY_LENGTH_TOO_LONG
ARRAY_LENGTH_TOO_SHORT
ARRAY_EMPTY
EXPECTED_BOOLEAN
EXPECTED_INTEGER
EXPECTED_FLOAT
EXPECTED_STRING
EXPECTED_OBJECT
EXPECTED_ARRAY
EXPECTED_MAP
EXPECTED_BASE64_ENCODED_BYTE_ARRAY
INVALID_ARRAY_VALUE
INVALID_ENUM_VALUE
INVALID_CONTENT_TYPE
INVALID_FORM_VALUE
ONE_INSTRUMENT_EXPECTED
NO_FIELDS_SET
DEPRECATED_FIELD_SET
CARD_EXPIRED
INVALID_EXPIRATION
INVALID_EXPIRATION_YEAR
INVALID_EXPIRATION_DATE
UNSUPPORTED_CARD_BRAND
UNSUPPORTED_ENTRY_METHOD
INVALID_ENCRYPTED_CARD
INVALID_CARD
DELAYED_TRANSACTION_EXPIRED
DELAYED_TRANSACTION_CANCELED
DELAYED_TRANSACTION_CAPTURED
DELAYED_TRANSACTION_FAILED
CARD_TOKEN_EXPIRED
CARD_TOKEN_USED
AMOUNT_TOO_HIGH
UNSUPPORTED_INSTRUMENT_TYPE
REFUND_AMOUNT_INVALID
REFUND_ALREADY_PENDING
PAYMENT_NOT_REFUNDABLE
INVALID_CARD_DATA
LOCATION_MISMATCH
IDEMPOTENCY_KEY_REUSED
UNEXPECTED_VALUE
SANDBOX_NOT_SUPPORTED
INVALID_EMAIL_ADDRESS
INVALID_PHONE_NUMBER
CHECKOUT_EXPIRED
BAD_CERTIFICATE
CARD_DECLINED
VERIFY_CVV_FAILURE
VERIFY_AVS_FAILURE
CARD_DECLINED_CALL_ISSUER
NOT_FOUND
APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND
METHOD_NOT_ALLOWED
REQUEST_TIMEOUT
CONFLICT
REQUEST_ENTITY_TOO_LARGE
UNSUPPORTED_MEDIA_TYPE
RATE_LIMITED
NOT_IMPLEMENTED
SERVICE_UNAVAILABLE
GATEWAY_TIMEOUT

InventoryAlertType

Indicates whether Square should alert the merchant when the inventory quantity of a CatalogItemVariation is low.

Fields

Name Description
NONE

The variation does not display an alert.

LOW_QUANTITY

The variation generates an alert when its quantity is low.

InventoryChangeType

Indicates how the inventory change was applied to a tracked quantity of items.

Fields

Name Description
PHYSICAL_COUNT

The change occurred as part of a physical count update.

ADJUSTMENT

The change occurred as part of the normal lifecycle of goods (e.g., as an inventory adjustment).

TRANSFER

The change occurred as part of an inventory transfer.

InventoryState

Indicates the state of a tracked item quantity in the lifecycle of goods.

Fields

Name Description
CUSTOM

The related quantity of items are in a custom state. READ-ONLY: the Inventory API cannot move quantities to or from this state.

IN_STOCK

The related quantity of items are on hand and available for sale.

SOLD

The related quantity of items were sold as part of an itemized transaction. Quantities in the SOLD state are no longer tracked.

RETURNED_BY_CUSTOMER

The related quantity of items were returned through the Square Point of Sale application, but are not yet available for sale. READ-ONLY: the Inventory API cannot move quantities to or from this state.

RESERVED_FOR_SALE

The related quantity of items are on hand, but not currently available for sale. READ-ONLY: the Inventory API cannot move quantities to or from this state.

SOLD_ONLINE

The related quantity of items were sold online. READ-ONLY: the Inventory API cannot move quantities to or from this state.

ORDERED_FROM_VENDOR

The related quantity of items were ordered from a vendor but not yet received. READ-ONLY: the Inventory API cannot move quantities to or from this state.

RECEIVED_FROM_VENDOR

The related quantity of items were received from a vendor but are not yet available for sale. READ-ONLY: the Inventory API cannot move quantities to or from this state.

IN_TRANSIT_TO

The related quantity of items are in transit between locations. READ-ONLY*: the Inventory API cannot move quantities to or from this state.

NONE

A placeholder indicating that the related quantity of items are not currently tracked in Square. Transferring quantities from the NONE state to a tracked state (e.g., IN_STOCK) introduces stock into the system.

WASTE

The related quantity of items are lost or damaged and cannot be sold.

UNLINKED_RETURN

The related quantity of items were returned but not linked to a previous transaction. Unlinked returns are not tracked in Square. Transferring a quantity from UNLINKED_RETURN to a tracked state (e.g., IN_STOCK) introduces new stock into the system.

LocationCapability

Indicates payment capabilities that a business's location might or might not have enabled.

Fields

Name Description
CREDIT_CARD_PROCESSING

The location can process credit cards with Square.

If this value is not present in a Location's' capabilities array, the location cannot process credit cards.

LocationStatus

Indicates the location's status.

Fields

Name Description
ACTIVE

A fully operational location. The location can be used across all Square products and APIs.

INACTIVE

A functionally limited location. The location can only be used via Square APIs.

NOTE: We strongly discourage the use of inactive locations. Making API calls with inactive locations will cause complications if the restrictions on inactive locations increase in the future.

LocationType

Indicates the location's type.

Fields

Name Description
PHYSICAL

A physical location of a business.

MOBILE

A location without a physical address. For example: mobile food truck, online store, phone app.

OrderLineItemDiscountScope

Indicates whether this is a line item or order level discount.

Fields

Name Description
OTHER_DISCOUNT_SCOPE

Used for reporting only. The original transaction discount scope is currently not supported by the API.

LINE_ITEM

The discount should be applied to a single line item.

ORDER

The discount should be applied to the entire order.

OrderLineItemDiscountType

Indicates how the discount is applied to the associated line item or order.

Fields

Name Description
UNKNOWN_DISCOUNT

Used for reporting only. The original transaction discount type is currently not supported by the API.

FIXED_PERCENTAGE

Apply the discount as a fixed percentage (e.g., 5%) off the item price.

FIXED_AMOUNT

Apply the discount as a fixed monetary value (e.g., $1.00) off the item price.

VARIABLE_PERCENTAGE

Apply the discount as a variable percentage off the item price.

The variable percentage is defined in Register POS apps. Specific value is assigned at the time of the purchase.

VARIABLE_AMOUNT

Apply the discount as a variable amount off the item price.

The variable amount is defined in Square POS app. Specific value is assigned at the time of the purchase.

OrderLineItemTaxType

Indicates how the tax is applied to the associated line item or order.

Fields

Name Description
UNKNOWN_TAX

Used for reporting only. The original transaction tax type is currently not supported by the API.

ADDITIVE

The tax is an additive tax. The tax amount is added on top of the price. For example, a $1.00 item with a 10% additive tax would have a total cost to the buyer of $1.10.

INCLUSIVE

The tax is an inclusive tax. Inclusive taxes are already included in the line item price or order total. For example, a $1.00 item with a 10% inclusive tax would have a pre-tax cost of $0.91 (91 cents) and a $0.09 (9 cents) tax for a total cost of $1 to the buyer.

Product

Indicates the Square product used to generate an inventory change.

Fields

Name Description
SQUARE_POS

Square Point of Sale application.

EXTERNAL_API

Square Connect APIs (Transactions API, Checkout API).

BILLING

A Square subscription (various products).

APPOINTMENTS

Square Appointments.

INVOICES

Square Invoices.

ONLINE_STORE

Square Online Store.

PAYROLL

Square Payroll.

DASHBOARD

Square Dashboard

ITEM_LIBRARY_IMPORT

Item Library Import

OTHER

A Square product that does not match any other value.

RefundStatus

Indicates a refund's current status.

Fields

Name Description
PENDING

The refund is pending.

APPROVED

The refund has been approved by Square.

REJECTED

The refund has been rejected by Square.

FAILED

The refund failed.

RegisterDomainResponseStatus

The status of domain registration.

Fields

Name Description
PENDING

The domain is added, but not verified.

VERIFIED

The domain is added and verified. It can be used to accept Apple Pay transactions.

SortOrder

The order (e.g., chronological or alphabetical) in which results from a request are returned.

Fields

Name Description
DESC

The results are returned in descending (e.g., newest-first or Z-A) order.

ASC

The results are returned in ascending (e.g., oldest-first or A-Z) order.

TaxCalculationPhase

When to calculate the taxes due on a cart.

Fields

Name Description
TAX_SUBTOTAL_PHASE

The fee is calculated based on the payment's subtotal.

TAX_TOTAL_PHASE

The fee is calculated based on the payment's total.

TaxInclusionType

Whether to the tax amount should be additional to or included in to the CatalogItem price.

Fields

Name Description
ADDITIVE

The tax is an additive tax. The tax amount is added on top of the CatalogItemVariation price. For example, a $1.00 item with a 10% additive tax would have a total cost to the buyer of $1.10.

INCLUSIVE

The tax is an inclusive tax. The tax amount is included in the CatalogItemVariation price. For example, a $1.00 item with a 10% inclusive tax would have a total cost to the buyer of $1.00, with $0.91 (91 cents) of that total being the cost of the item and $0.09 (9 cents) being tax.

TenderCardDetailsEntryMethod

Indicates the method used to enter the card's details.

Fields

Name Description
SWIPED

The card was swiped through a Square reader or Square stand.

KEYED

The card information was keyed manually into Square Point of Sale or a Square-hosted web form.

EMV

The card was processed via EMV with a Square reader.

ON_FILE

The buyer's card details were already on file with Square.

CONTACTLESS

The card was processed via a contactless (i.e., NFC) transaction with a Square reader.

TenderCardDetailsStatus

Indicates the card transaction's current status.

Fields

Name Description
AUTHORIZED

The card transaction has been authorized but not yet captured.

CAPTURED

The card transaction was authorized and subsequently captured (i.e., completed).

VOIDED

The card transaction was authorized and subsequently voided (i.e., canceled).

FAILED

The card transaction failed.

TenderType

Indicates a tender's type.

Fields

Name Description
CARD

A credit card.

CASH

Cash.

THIRD_PARTY_CARD

A credit card processed with a card processor other than Square.

This value applies only to merchants in countries where Square does not yet provide card processing.

SQUARE_GIFT_CARD

A Square gift card.

NO_SALE

This tender represents the register being opened for a "no sale" event.

OTHER

A form of tender that does not match any other value.

TransactionProduct

Indicates the Square product used to process a transaction.

Fields

Name Description
REGISTER

Square Point of Sale.

EXTERNAL_API

The Square Connect API.

BILLING

A Square subscription for one of multiple products.

APPOINTMENTS

Square Appointments.

INVOICES

Square Invoices.

ONLINE_STORE

Square Online Store.

PAYROLL

Square Payroll.

OTHER

A Square product that does not match any other value.

Connect API v2 Conventions

Client libraries

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

Swagger specification

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

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

Running Postman

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

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

Run in Postman

Endpoint paths

Connect API endpoints are hosted from the base URL https://connect.squareup.com. For example, the ListTransactions endpoint's full path is:

https://connect.squareup.com/v2/locations/{location_id}/transactions

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

API versions

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

Endpoint names and return values

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

Action HTTP Method Description
Create POST Creates and persists an entity of the corresponding type.
List GET Returns all instances of a particular entity that match query parameters you provide.
Retrieve GET Returns the single instance of an entity that matches the identifier you provide.
Update PUT Modifies the existing entity that matches the identifier you provide.
Delete DELETE Deletes the existing entity that matches the identifier you provide. Deleted entities cannot be retrieved or undeleted.

For example, the ListTransactions endpoint returns an array of processed payments, and the CreateCustomer endpoint creates and persists a customer.

Request and response headers

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

Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

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

POST and PUT requests must include one additional header:

Content-Type: application/json

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

Providing parameters

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

GET and DELETE requests

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

https://connect.squareup.com/v2/locations/LOCATION_ID/transactions?sort_order=ASC

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

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

POST and PUT requests

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

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

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

Working with monetary amounts

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

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

The amount field is always in the smallest denomination of the currency indicated by currency_code. When currency_code is USD (US dollars), amount is in cents. The object shown above represents 4 US dollars.

Note: Businesses located in the United States or Canada can set monitary amounts as low as 1 cent. For example, the following structure sets a monitary amount of 50 cents USD.

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

Important: Unlike version 1 of the Connect API, all monetary amounts returned by v2 endpoints are positive. (In v1, monetary amounts are negative if they represent money being paid by a merchant, instead of money being paid to a merchant.)

The currency_code field is in ISO 4217 format.

Working with dates

All representations of dates are strings in RFC 3339 format.

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

Date strings returned by the Connect API are always UTC.

Date ranges

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

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

  • When sort_order is DESC (newest-first), begin_time is exclusive and end_time is inclusive.
  • When sort_order is ASC (oldest-first), begin_time is inclusive and end_time is exclusive.

The described date range must cover at least one millisecond.

Idempotency keys

Certain Connect API endpoints (currently Charge and CreateRefund) require an idempotency_key string parameter. Any time you want to initiate a new card transaction or refund, you should provide a new, unique value for this parameter.

Virtually all popular programming languages provide a function for generating unique strings. For example:

Language Function
Ruby SecureRandom.uuid
PHP uniqid
Java UUID.randomUUID
Python uuid

Idempotency keys must be unique per business, not per application. They cannot exceed 128 characters.

If you're unsure whether a particular transaction succeeded (for example, if you don't receive a response from an endpoint for some reason), you can reattempt it with the same idempotency key without worrying about creating a duplicate transaction.

Paginating results

List endpoints such as ListTransactions might paginate the results they return. This means that instead of returning all results in a single response, these endpoints might return some of the results, along with a cursor in the response body that links to the next set of results.

Send a followup request to the same endpoint, providing the cursor value returned in the previous response as a query parameter, to fetch the next set of results. Repeat this process until you receive a response without a cursor.

Handling duplicate results

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

Handling the enum value OTHER

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

Enum values besides OTHER never change retroactively.

Replacing application credentials

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

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

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

Rate limiting

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

Handling errors

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

All Connect v2 endpoints include an errors array in their response body if any errors occurred during a request. The response body has the following structure:

{
  "errors": [
    {
      "category": "AUTHENTICATION_ERROR",
      "code": "UNAUTHORIZED",
      "detail": "This request could not be authorized."
    }
  ]
}

Each Error in the array can have the following fields:

  • category indicates which high-level category the error falls into. This value never changes for a particular error. See ErrorCategory for possible values.
  • code indicates the exact type of error that occurred. This value never changes for a particular error. See ErrorCode for possible values.
  • detail is a human-readable string that will help you diagnose the error. This value can change for a particular error.
  • field is the name of the field provided in the original request that the error pertains to, if any.

Using OAuth

If you are developing a Connect v2 application for multiple merchants to use, you must request specific permissions from those merchants with the OAuth API. See the OAuth API Reference for more information.

API Sandbox Credentials

Connect API v2 provides a sandbox that lets you test out API endpoints in a non-production environment. Transactions created in the sandbox are not sent through to card networks, and cards are never charged. Below are API credentials you can use to play with Square's APIs.

Access Token
Application ID
Location ID

Read the HTTP PHP Ruby Java C# Python Node.js documentation:

Setup your SDK environment

To set up your PHP Ruby Java C# Python Node.js SDK, follow the example below:

// Setup authorization
Configuration::getDefaultConfiguration()->setAccessToken($ACCESS_TOKEN);
require 'square_connect'
# Setup authorization.
SquareConnect.configure do |config|
  config.access_token = ACCESS_TOKEN
end
import com.squareup.connect.*;
import com.squareup.connect.auth.*;
// Configure OAuth2 access token for authorization: oauth2

ApiClient defaultClient = Configuration.getDefaultApiClient();
OAuth oauth2 = (OAuth) defaultClient.getAuthentication("oauth2");
oauth2.setAccessToken(ACCESS_TOKEN);
using Square.Connect.Client;
// Setup authorization.
Configuration.Default.AccessToken = ACCESS_TOKEN;
import squareconnect
# Setup authorization.
squareconnect.configuration.access_token = ACCESS_TOKEN
const SquareConnect = require('square-connect');
# Setup authorization.
const defaultClient = SquareConnect.ApiClient.instance;
const oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = ACCESS_TOKEN