> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinkfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# square-catalog
> Square Catalog & Orders
**Server path:** `/square-catalog` | **Type:** Application | **PCID required:** Yes
## Tools
| Tool | Description |
| ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| [`square_catalog_batch_change_inventory`](#square_catalog_batch_change_inventory) | BatchChangeInventory |
| [`square_catalog_batch_delete_catalog_objects`](#square_catalog_batch_delete_catalog_objects) | BatchDeleteCatalogObjects |
| [`square_catalog_batch_retrieve_catalog_objects`](#square_catalog_batch_retrieve_catalog_objects) | BatchRetrieveCatalogObjects |
| [`square_catalog_batch_retrieve_inventory_changes`](#square_catalog_batch_retrieve_inventory_changes) | BatchRetrieveInventoryChanges |
| [`square_catalog_batch_retrieve_inventory_counts`](#square_catalog_batch_retrieve_inventory_counts) | BatchRetrieveInventoryCounts |
| [`square_catalog_batch_retrieve_orders`](#square_catalog_batch_retrieve_orders) | BatchRetrieveOrders |
| [`square_catalog_batch_upsert_catalog_objects`](#square_catalog_batch_upsert_catalog_objects) | BatchUpsertCatalogObjects |
| [`square_catalog_bulk_delete_order_custom_attributes`](#square_catalog_bulk_delete_order_custom_attributes) | BulkDeleteOrderCustomAttributes |
| [`square_catalog_bulk_upsert_order_custom_attributes`](#square_catalog_bulk_upsert_order_custom_attributes) | BulkUpsertOrderCustomAttributes |
| [`square_catalog_calculate_order`](#square_catalog_calculate_order) | CalculateOrder |
| [`square_catalog_clone_order`](#square_catalog_clone_order) | CloneOrder |
| [`square_catalog_create_catalog_image`](#square_catalog_create_catalog_image) | CreateCatalogImage |
| [`square_catalog_create_order`](#square_catalog_create_order) | CreateOrder |
| [`square_catalog_create_order_custom_attribute_definition`](#square_catalog_create_order_custom_attribute_definition) | CreateOrderCustomAttributeDefinition |
| [`square_catalog_delete_object`](#square_catalog_delete_object) | DeleteCatalogObject |
| [`square_catalog_delete_order_custom_attribute`](#square_catalog_delete_order_custom_attribute) | DeleteOrderCustomAttribute |
| [`square_catalog_delete_order_custom_attribute_definition`](#square_catalog_delete_order_custom_attribute_definition) | DeleteOrderCustomAttributeDefinition |
| [`square_catalog_info`](#square_catalog_info) | CatalogInfo |
| [`square_catalog_list_catalog`](#square_catalog_list_catalog) | ListCatalog |
| [`square_catalog_list_order_custom_attribute_definitions`](#square_catalog_list_order_custom_attribute_definitions) | ListOrderCustomAttributeDefinitions |
| [`square_catalog_list_order_custom_attributes`](#square_catalog_list_order_custom_attributes) | ListOrderCustomAttributes |
| [`square_catalog_pay_order`](#square_catalog_pay_order) | PayOrder |
| [`square_catalog_retrieve_catalog_object`](#square_catalog_retrieve_catalog_object) | RetrieveCatalogObject |
| [`square_catalog_retrieve_inventory_adjustment`](#square_catalog_retrieve_inventory_adjustment) | RetrieveInventoryAdjustment |
| [`square_catalog_retrieve_inventory_count`](#square_catalog_retrieve_inventory_count) | RetrieveInventoryCount |
| [`square_catalog_retrieve_inventory_physical_count`](#square_catalog_retrieve_inventory_physical_count) | RetrieveInventoryPhysicalCount |
| [`square_catalog_retrieve_inventory_transfer`](#square_catalog_retrieve_inventory_transfer) | RetrieveInventoryTransfer |
| [`square_catalog_retrieve_order`](#square_catalog_retrieve_order) | RetrieveOrder |
| [`square_catalog_retrieve_order_custom_attribute`](#square_catalog_retrieve_order_custom_attribute) | RetrieveOrderCustomAttribute |
| [`square_catalog_retrieve_order_custom_attribute_definition`](#square_catalog_retrieve_order_custom_attribute_definition) | RetrieveOrderCustomAttributeDefinition |
| [`square_catalog_search_catalog_items`](#square_catalog_search_catalog_items) | SearchCatalogItems |
| [`square_catalog_search_catalog_objects`](#square_catalog_search_catalog_objects) | SearchCatalogObjects |
| [`square_catalog_search_orders`](#square_catalog_search_orders) | SearchOrders |
| [`square_catalog_update_catalog_image`](#square_catalog_update_catalog_image) | UpdateCatalogImage |
| [`square_catalog_update_item_modifier_lists`](#square_catalog_update_item_modifier_lists) | UpdateItemModifierLists |
| [`square_catalog_update_item_taxes`](#square_catalog_update_item_taxes) | UpdateItemTaxes |
| [`square_catalog_update_order`](#square_catalog_update_order) | UpdateOrder |
| [`square_catalog_update_order_custom_attribute_definition`](#square_catalog_update_order_custom_attribute_definition) | UpdateOrderCustomAttributeDefinition |
| [`square_catalog_upsert_catalog_object`](#square_catalog_upsert_catalog_object) | UpsertCatalogObject |
| [`square_catalog_upsert_order_custom_attribute`](#square_catalog_upsert_order_custom_attribute) | UpsertOrderCustomAttribute |
***
## square\_catalog\_batch\_change\_inventory
BatchChangeInventory
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ------------------------- | --------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `changes` | object\[] | No | — | 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. | |
| `idempotency_key` | string | Yes | — | A client-supplied, universally unique identifier (UUID) for the request. See [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) in the [API Development 101](https://developer.squareup.com/docs/buildbasics) section for more information. | |
| `ignore_unchanged_counts` | boolean | null | No | — | Indicates whether the current physical count should be ignored if the quantity is unchanged since the last physical count. Default: `true`. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"changes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"PHYSICAL_COUNT",
"ADJUSTMENT",
"TRANSFER"
],
"description": "Indicates how the inventory change was applied to a tracked product quantity."
},
"physical_count": {
"type": "object",
"description": "Represents the quantity of an item variation that is physically present at a specific location, verified by a seller or a seller's employee. For example, a physical count might come from an employee counting the item variations on hand or from syncing with an external system."
},
"adjustment": {
"type": "object",
"description": "Represents a change in state or quantity of product inventory at a particular time and location."
},
"transfer": {
"type": "object",
"description": "Represents the transfer of a quantity of product inventory at a particular time from one location to another."
},
"measurement_unit": {
"type": "object",
"description": "Represents the unit used to measure a `CatalogItemVariation` and specifies the precision for decimal quantities."
},
"measurement_unit_id": {
"type": "string",
"description": "The ID of the [CatalogMeasurementUnit](entity:CatalogMeasurementUnit) object representing the catalog measurement unit associated with the inventory change."
}
}
},
"description": "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."
},
"idempotency_key": {
"type": "string",
"description": "A client-supplied, universally unique identifier (UUID) for the request. See [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) in the [API Development 101](https://developer.squareup.com/docs/buildbasics) section for more information."
},
"ignore_unchanged_counts": {
"type": [
"boolean",
"null"
],
"description": "Indicates whether the current physical count should be ignored if the quantity is unchanged since the last physical count. Default: `true`."
}
},
"required": [
"PCID",
"idempotency_key"
]
}
```
***
## square\_catalog\_batch\_delete\_catalog\_objects
BatchDeleteCatalogObjects
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------ | --------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object_ids` | string\[] | Yes | — | 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 CatalogItemVariation. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"object_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "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 CatalogItemVariation."
}
},
"required": [
"PCID",
"object_ids"
]
}
```
***
## square\_catalog\_batch\_retrieve\_catalog\_objects
BatchRetrieveCatalogObjects
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ------------------------------- | --------- | -------- | ------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `catalog_version` | integer | null | No | — | The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the CatalogObjects' `version` attribute. If not included, results will be from the current version of the catalog. |
| `include_category_path_to_root` | boolean | null | No | — | Specifies whether or not to include the `path_to_root` list for each returned category instance. The `path_to_root` list consists of `CategoryPathToRootNode` objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the `path_to_root` list is empty and is not returned in the response payload. |
| `include_deleted_objects` | boolean | null | No | — | Indicates whether to include (`true`) or not (`false`) in the response deleted objects, namely, those with the `is_deleted` attribute set to `true`. |
| `include_related_objects` | boolean | null | No | — | If `true`, the response will include additional objects that are related to the requested objects. Related objects are defined as any objects referenced by ID by the results in the `objects` field of the response. These objects are put in the `related_objects` field. Setting this to `true` is helpful when the objects are needed for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example, if the `objects` field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects 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. Default value: `false` |
| `object_ids` | string\[] | Yes | — | The IDs of the CatalogObjects to be retrieved. | |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"catalog_version": {
"type": [
"integer",
"null"
],
"description": "The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the [CatalogObject](entity:CatalogObject)s' `version` attribute. If not included, results will be from the current version of the catalog."
},
"include_category_path_to_root": {
"type": [
"boolean",
"null"
],
"description": "Specifies whether or not to include the `path_to_root` list for each returned category instance. The `path_to_root` list consists of `CategoryPathToRootNode` objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the `path_to_root` list is empty and is not returned in the response payload."
},
"include_deleted_objects": {
"type": [
"boolean",
"null"
],
"description": "Indicates whether to include (`true`) or not (`false`) in the response deleted objects, namely, those with the `is_deleted` attribute set to `true`."
},
"include_related_objects": {
"type": [
"boolean",
"null"
],
"description": "If `true`, the response will include additional objects that are related to the requested objects. Related objects are defined as any objects referenced by ID by the results in the `objects` field of the response. These objects are put in the `related_objects` field. Setting this to `true` is helpful when the objects are needed for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example, if the `objects` field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects 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. Default value: `false`"
},
"object_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The IDs of the CatalogObjects to be retrieved."
}
},
"required": [
"PCID",
"object_ids"
]
}
```
***
## square\_catalog\_batch\_retrieve\_inventory\_changes
BatchRetrieveInventoryChanges
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| -------------------- | --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `catalog_object_ids` | string\[] | No | — | The filter to return results by `CatalogObject` ID. The filter is only applicable when set. The default value is null. | |
| `cursor` | string | null | No | — | 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 the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information. |
| `limit` | integer | null | No | — | The number of records to return. |
| `location_ids` | string\[] | No | — | The filter to return results by `Location` ID. The filter is only applicable when set. The default value is null. | |
| `states` | string\[] | No | — | The filter to return `ADJUSTMENT` query results by `InventoryState`. This filter is only applied when set. The default value is null. | |
| `types` | string\[] | No | — | The filter to return results by `InventoryChangeType` values other than `TRANSFER`. The default value is `[PHYSICAL_COUNT, ADJUSTMENT]`. | |
| `updated_after` | string | null | No | — | The filter to return results with their `calculated_at` value after the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`). |
| `updated_before` | string | null | No | — | The filter to return results with their `created_at` or `calculated_at` value strictly before the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"catalog_object_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The filter to return results by `CatalogObject` ID. The filter is only applicable when set. The default value is null."
},
"cursor": {
"type": [
"string",
"null"
],
"description": "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 the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "The number of [records](entity:InventoryChange) to return."
},
"location_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The filter to return results by `Location` ID. The filter is only applicable when set. The default value is null."
},
"states": {
"type": "array",
"items": {
"type": "string",
"enum": [
"CUSTOM",
"IN_STOCK",
"SOLD",
"RETURNED_BY_CUSTOMER",
"RESERVED_FOR_SALE",
"SOLD_ONLINE",
"ORDERED_FROM_VENDOR",
"RECEIVED_FROM_VENDOR",
"IN_TRANSIT_TO",
"NONE",
"WASTE",
"UNLINKED_RETURN",
"COMPOSED",
"DECOMPOSED",
"SUPPORTED_BY_NEWER_VERSION",
"IN_TRANSIT"
]
},
"description": "The filter to return `ADJUSTMENT` query results by `InventoryState`. This filter is only applied when set. The default value is null."
},
"types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"PHYSICAL_COUNT",
"ADJUSTMENT",
"TRANSFER"
]
},
"description": "The filter to return results by `InventoryChangeType` values other than `TRANSFER`. The default value is `[PHYSICAL_COUNT, ADJUSTMENT]`."
},
"updated_after": {
"type": [
"string",
"null"
],
"description": "The filter to return results with their `calculated_at` value after the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`)."
},
"updated_before": {
"type": [
"string",
"null"
],
"description": "The filter to return results with their `created_at` or `calculated_at` value strictly before the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`)."
}
},
"required": [
"PCID"
]
}
```
***
## square\_catalog\_batch\_retrieve\_inventory\_counts
BatchRetrieveInventoryCounts
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| -------------------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `catalog_object_ids` | string\[] | No | — | The filter to return results by `CatalogObject` ID. The filter is applicable only when set. The default is null. | |
| `cursor` | string | null | No | — | 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 the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information. |
| `limit` | integer | null | No | — | The number of records to return. |
| `location_ids` | string\[] | No | — | The filter to return results by `Location` ID. This filter is applicable only when set. The default is null. | |
| `states` | string\[] | No | — | The filter to return results by `InventoryState`. The filter is only applicable when set. Ignored are untracked states of `NONE`, `SOLD`, and `UNLINKED_RETURN`. The default is null. | |
| `updated_after` | string | null | No | — | The filter to return results with their `calculated_at` value after the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"catalog_object_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The filter to return results by `CatalogObject` ID. The filter is applicable only when set. The default is null."
},
"cursor": {
"type": [
"string",
"null"
],
"description": "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 the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "The number of [records](entity:InventoryCount) to return."
},
"location_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The filter to return results by `Location` ID. This filter is applicable only when set. The default is null."
},
"states": {
"type": "array",
"items": {
"type": "string",
"enum": [
"CUSTOM",
"IN_STOCK",
"SOLD",
"RETURNED_BY_CUSTOMER",
"RESERVED_FOR_SALE",
"SOLD_ONLINE",
"ORDERED_FROM_VENDOR",
"RECEIVED_FROM_VENDOR",
"IN_TRANSIT_TO",
"NONE",
"WASTE",
"UNLINKED_RETURN",
"COMPOSED",
"DECOMPOSED",
"SUPPORTED_BY_NEWER_VERSION",
"IN_TRANSIT"
]
},
"description": "The filter to return results by `InventoryState`. The filter is only applicable when set. Ignored are untracked states of `NONE`, `SOLD`, and `UNLINKED_RETURN`. The default is null."
},
"updated_after": {
"type": [
"string",
"null"
],
"description": "The filter to return results with their `calculated_at` value after the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`)."
}
},
"required": [
"PCID"
]
}
```
***
## square\_catalog\_batch\_retrieve\_orders
BatchRetrieveOrders
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ------------- | --------- | -------- | ------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `location_id` | string | null | No | — | The ID of the location for these orders. This field is optional: omit it to retrieve orders within the scope of the current authorization's merchant ID. |
| `order_ids` | string\[] | Yes | — | The IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request. | |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"location_id": {
"type": [
"string",
"null"
],
"description": "The ID of the location for these orders. This field is optional: omit it to retrieve orders within the scope of the current authorization's merchant ID."
},
"order_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request."
}
},
"required": [
"PCID",
"order_ids"
]
}
```
***
## square\_catalog\_batch\_upsert\_catalog\_objects
BatchUpsertCatalogObjects
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | --------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batches` | object\[] | Yes | — | 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](https://developer.squareup.com/docs/build-basics/working-with-dates), 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. |
| `idempotency_key` | string | Yes | — | 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"batches": {
"type": "array",
"items": {
"type": "object",
"properties": {
"objects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Possible types of CatalogObjects returned from the catalog, each containing type-specific properties in the `*_data` field corresponding to the specified object type."
},
"id": {
"type": "string",
"description": "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": {
"type": "string",
"description": "Last modification [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) 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": {
"type": "integer",
"description": "The version of the object. When updating an object, the version supplied must match the version in the database, otherwise the write will be rejected as conflicting."
},
"is_deleted": {
"type": "boolean",
"description": "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."
},
"custom_attribute_values": {
"type": "object",
"description": "A map (key-value pairs) of application-defined custom attribute values. The value of a key-value pair is a [CatalogCustomAttributeValue](entity:CatalogCustomAttributeValue) object. The key is the `key` attribute value defined in the associated [CatalogCustomAttributeDefinition](entity:CatalogCustomAttributeDefinition) object defined by the application making the request. If the `CatalogCustomAttributeDefinition` object is defined by another application, the `CatalogCustomAttributeDefinition`'s key attribute value is prefixed by the defining application ID. For example, if the `CatalogCustomAttributeDefinition` has a `key` attribute of `\"cocoa_brand\"` and the defining application ID is `\"abcd1234\"`, the key in the map is `\"abcd1234:cocoa_brand\"` if the application making the request is different from the application defining the custom attribute definition. Otherwise, the key used in the map is simply `\"cocoa_brand\"`. Application-defined custom attributes are set at a global (location-independent) level. Custom attribute values are intended to store additional information about a catalog object or associations with an entity in another system. Do not use custom attributes to store any sensitive information (personally identifiable information, card details, etc.)."
},
"catalog_v1_ids": {
"type": "array",
"description": "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": {
"type": "boolean",
"description": "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": {
"type": "array",
"description": "A list of locations where the object is present, even if `present_at_all_locations` is `false`. This can include locations that are deactivated."
},
"absent_at_location_ids": {
"type": "array",
"description": "A list of locations where the object is not present, even if `present_at_all_locations` is `true`. This can include locations that are deactivated."
},
"item_data": {
"type": "object",
"description": "A [CatalogObject](entity:CatalogObject) instance of the `ITEM` type, also referred to as an item, in the catalog."
},
"category_data": {
"type": "object",
"description": "A category to which a `CatalogItem` instance belongs."
},
"item_variation_data": {
"type": "object",
"description": "An item variation, representing a product for sale, in the Catalog object model. Each [item](entity:CatalogItem) must have at least one item variation and can have at most 250 item variations. An item variation can be sellable, stockable, or both if it has a unit of measure for its count for the sold number of the variation, the stocked number of the variation, or both. For example, when a variation representing wine is stocked and sold by the bottle, the variation is both stockable and sellable. But when a variation of the wine is sold by the glass, the sold units cannot be used as a measure of the stocked units. This by-the-glass variation is sellable, but not stockable. To accurately keep track of the wine's inventory count at any time, the sellable count must be converted to stockable count. Typically, the seller defines this unit conversion. For example, 1 bottle equals 5 glasses. The Square API exposes the `stockable_conversion` property on the variation to specify the conversion. Thus, when two glasses of the wine are sold, the sellable count decreases by 2, and the stockable count automatically decreases by 0.4 bottle according to the conversion."
},
"tax_data": {
"type": "object",
"description": "A tax applicable to an item."
},
"discount_data": {
"type": "object",
"description": "A discount applicable to items."
},
"modifier_list_data": {
"type": "object",
"description": "A container for a list of modifiers, or a text-based modifier. For text-based modifiers, this represents text configuration for an item. (For example, custom text to print on a t-shirt). For non text-based modifiers, this represents a list of modifiers that can be applied to items at the time of sale. (For example, a list of condiments for a hot dog, or a list of ice cream flavors). Each element of the modifier list is a `CatalogObject` instance of the `MODIFIER` type."
},
"modifier_data": {
"type": "object",
"description": "A modifier that can be applied to items at the time of sale. For example, a cheese modifier for a burger, or a flavor modifier for a serving of ice cream."
},
"time_period_data": {
"type": "object",
"description": "Represents a time period - either a single period or a repeating period."
},
"product_set_data": {
"type": "object",
"description": "Represents a collection of catalog objects for the purpose of applying a `PricingRule`. Including a catalog object will include all of its subtypes. For example, including a category in a product set will include all of its items and associated item variations in the product set. Including an item in a product set will also include its item variations."
},
"pricing_rule_data": {
"type": "object",
"description": "Defines how discounts are automatically applied to a set of items that match the pricing rule during the active time period."
},
"image_data": {
"type": "object",
"description": "An image file to use in Square catalogs. It can be associated with `CatalogItem`, `CatalogItemVariation`, `CatalogCategory`, and `CatalogModifierList` objects. Only the images on items and item variations are exposed in Dashboard. Only the first image on an item is displayed in Square Point of Sale (SPOS). Images on items and variations are displayed through Square Online Store. Images on other object types are for use by 3rd party application developers."
},
"measurement_unit_data": {
"type": "object",
"description": "Represents the unit used to measure a `CatalogItemVariation` and specifies the precision for decimal quantities."
},
"subscription_plan_data": {
"type": "object",
"description": "Describes a subscription plan. A subscription plan represents what you want to sell in a subscription model, and includes references to each of the associated subscription plan variations. For more information, see [Subscription Plans and Variations](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations)."
},
"item_option_data": {
"type": "object",
"description": "A group of variations for a `CatalogItem`."
},
"item_option_value_data": {
"type": "object",
"description": "An enumerated value that can link a `CatalogItemVariation` to an item option as one of its item option values."
},
"custom_attribute_definition_data": {
"type": "object",
"description": "Contains information defining a custom attribute. Custom attributes are intended to store additional information about a catalog object or to associate a catalog object with an entity in another system. Do not use custom attributes to store any sensitive information (personally identifiable information, card details, etc.). [Read more about custom attributes](https://developer.squareup.com/docs/catalog-api/add-custom-attributes)"
},
"quick_amounts_settings_data": {
"type": "object",
"description": "A parent Catalog Object model represents a set of Quick Amounts and the settings control the amounts."
},
"subscription_plan_variation_data": {
"type": "object",
"description": "Describes a subscription plan variation. A subscription plan variation represents how the subscription for a product or service is sold. For more information, see [Subscription Plans and Variations](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations)."
},
"availability_period_data": {
"type": "object",
"description": "Represents a time period of availability."
}
}
},
"description": "A list of CatalogObjects belonging to this batch."
}
},
"required": [
"objects"
]
},
"description": "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](https://developer.squareup.com/docs/build-basics/working-with-dates), 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."
},
"idempotency_key": {
"type": "string",
"description": "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](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information."
}
},
"required": [
"PCID",
"batches",
"idempotency_key"
]
}
```
***
## square\_catalog\_bulk\_delete\_order\_custom\_attributes
BulkDeleteOrderCustomAttributes
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `values` | object | Yes | — | A map of requests that correspond to individual delete operations for custom attributes. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"values": {
"type": "object",
"description": "A map of requests that correspond to individual delete operations for custom attributes."
}
},
"required": [
"PCID",
"values"
]
}
```
***
## square\_catalog\_bulk\_upsert\_order\_custom\_attributes
BulkUpsertOrderCustomAttributes
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `values` | object | Yes | — | A map of requests that correspond to individual upsert operations for custom attributes. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"values": {
"type": "object",
"description": "A map of requests that correspond to individual upsert operations for custom attributes."
}
},
"required": [
"PCID",
"values"
]
}
```
***
## square\_catalog\_calculate\_order
CalculateOrder
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------ | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `order` | object | Yes | — | Contains all information related to a single order to process with Square, including line items that specify the products to purchase. `Order` objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data. |
| `proposed_rewards` | object\[] | No | — | Identifies one or more loyalty reward tiers to apply during the order calculation. The discounts defined by the reward tiers are added to the order only to preview the effect of applying the specified rewards. The rewards do not correspond to actual redemptions; that is, no `reward`s are created. Therefore, the reward `id`s are random strings used only to reference the reward tier. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"order": {
"type": "object",
"description": "Contains all information related to a single order to process with Square, including line items that specify the products to purchase. `Order` objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.",
"properties": {
"id": {
"type": "string",
"description": "The order's unique ID."
},
"location_id": {
"type": "string",
"description": "The ID of the seller location that this order is associated with."
},
"reference_id": {
"type": "string",
"description": "A client-specified ID to associate an entity in another system with this order."
},
"source": {
"type": "object",
"description": "Represents the origination details of an order."
},
"customer_id": {
"type": "string",
"description": "The ID of the [customer](entity:Customer) associated with the order. You should specify a `customer_id` on the order (or the payment) to ensure that transactions are reliably linked to customers. Omitting this field might result in the creation of new [instant profiles](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles)."
},
"line_items": {
"type": "array",
"items": {
"type": "object"
},
"description": "The line items included in the order."
},
"taxes": {
"type": "array",
"items": {
"type": "object"
},
"description": "The list of all taxes associated with the order. Taxes can be scoped to either `ORDER` or `LINE_ITEM`. For taxes with `LINE_ITEM` scope, an `OrderLineItemAppliedTax` must be added to each line item that the tax applies to. For taxes with `ORDER` scope, the server generates an `OrderLineItemAppliedTax` for every line item. On reads, each tax in the list includes the total amount of that tax applied to the order. __IMPORTANT__: If `LINE_ITEM` scope is set on any taxes in this field, using the deprecated `line_items.taxes` field results in an error. Use `line_items.applied_taxes` instead."
},
"discounts": {
"type": "array",
"items": {
"type": "object"
},
"description": "The list of all discounts associated with the order. Discounts can be scoped to either `ORDER` or `LINE_ITEM`. For discounts scoped to `LINE_ITEM`, an `OrderLineItemAppliedDiscount` must be added to each line item that the discount applies to. For discounts with `ORDER` scope, the server generates an `OrderLineItemAppliedDiscount` for every line item. __IMPORTANT__: If `LINE_ITEM` scope is set on any discounts in this field, using the deprecated `line_items.discounts` field results in an error. Use `line_items.applied_discounts` instead."
},
"service_charges": {
"type": "array",
"items": {
"type": "object"
},
"description": "A list of service charges applied to the order."
},
"fulfillments": {
"type": "array",
"items": {
"type": "object"
},
"description": "Details about order fulfillment. Orders can only be created with at most one fulfillment. However, orders returned by the API might contain multiple fulfillments."
},
"returns": {
"type": "array",
"items": {
"type": "object"
},
"description": "A collection of items from sale orders being returned in this one. Normally part of an itemized return or exchange. There is exactly one `Return` object per sale `Order` being referenced."
},
"return_amounts": {
"type": "object",
"description": "A collection of various money amounts."
},
"net_amounts": {
"type": "object",
"description": "A collection of various money amounts."
},
"rounding_adjustment": {
"type": "object",
"description": "A rounding adjustment of the money being returned. Commonly used to apply cash rounding when the minimum unit of the account is smaller than the lowest physical denomination of the currency."
},
"tenders": {
"type": "array",
"items": {
"type": "object"
},
"description": "The tenders that were used to pay for the order."
},
"refunds": {
"type": "array",
"items": {
"type": "object"
},
"description": "The refunds that are part of this order."
},
"metadata": {
"type": "object",
"description": "Application-defined data attached to this order. Metadata fields are intended to store descriptive references or associations with an entity in another system or store brief information about the object. Square does not process this field; it only stores and returns it in relevant API calls. Do not use metadata to store any sensitive information (such as personally identifiable information or card details). Keys written by applications must be 60 characters or less and must be in the character set `[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a ':' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata)."
},
"created_at": {
"type": "string",
"description": "The timestamp for when the order was created, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")."
},
"updated_at": {
"type": "string",
"description": "The timestamp for when the order was last updated, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")."
},
"closed_at": {
"type": "string",
"description": "The timestamp for when the order reached a terminal [state](entity:OrderState), in RFC 3339 format (for example \"2016-09-04T23:59:33.123Z\")."
},
"state": {
"type": "string",
"description": "The state of the order.",
"enum": [
"OPEN",
"COMPLETED",
"CANCELED",
"DRAFT"
]
},
"version": {
"type": "integer",
"description": "The version number, which is incremented each time an update is committed to the order. Orders not created through the API do not include a version number and therefore cannot be updated. [Read more about working with versions](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders)."
},
"total_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"total_tax_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"total_discount_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"total_tip_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"total_service_charge_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"ticket_name": {
"type": "string",
"description": "A short-term identifier for the order (such as a customer first name, table number, or auto-generated order number that resets daily)."
},
"pricing_options": {
"type": "object",
"description": "Pricing options for an order. The options affect how the order's price is calculated. They can be used, for example, to apply automatic price adjustments that are based on preconfigured [pricing rules](entity:CatalogPricingRule)."
},
"rewards": {
"type": "array",
"items": {
"type": "object"
},
"description": "A set-like list of Rewards that have been added to the Order."
},
"net_amount_due_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
}
},
"required": [
"location_id"
]
},
"proposed_rewards": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The identifier of the reward."
},
"reward_tier_id": {
"type": "string",
"description": "The identifier of the reward tier corresponding to this reward."
}
},
"required": [
"id",
"reward_tier_id"
]
},
"description": "Identifies one or more loyalty reward tiers to apply during the order calculation. The discounts defined by the reward tiers are added to the order only to preview the effect of applying the specified rewards. The rewards do not correspond to actual redemptions; that is, no `reward`s are created. Therefore, the reward `id`s are random strings used only to reference the reward tier."
}
},
"required": [
"PCID",
"order"
]
}
```
***
## square\_catalog\_clone\_order
CloneOrder
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `idempotency_key` | string | null | No | — | A value you specify that uniquely identifies this clone request. If you are unsure whether a particular order was cloned successfully, you can reattempt the call with the same idempotency key without worrying about creating duplicate cloned orders. The originally cloned order is returned. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). |
| `order_id` | string | Yes | — | The ID of the order to clone. | |
| `version` | integer | No | — | An optional order version for concurrency protection. If a version is provided, it must match the latest stored version of the order to clone. If a version is not provided, the API clones the latest version. | |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"idempotency_key": {
"type": [
"string",
"null"
],
"description": "A value you specify that uniquely identifies this clone request. If you are unsure whether a particular order was cloned successfully, you can reattempt the call with the same idempotency key without worrying about creating duplicate cloned orders. The originally cloned order is returned. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
},
"order_id": {
"type": "string",
"description": "The ID of the order to clone."
},
"version": {
"type": "integer",
"description": "An optional order version for concurrency protection. If a version is provided, it must match the latest stored version of the order to clone. If a version is not provided, the API clones the latest version."
}
},
"required": [
"PCID",
"order_id"
]
}
```
***
## square\_catalog\_create\_catalog\_image
CreateCatalogImage
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------ | ------ | -------- | ------- | ----------------- |
| `image_file` | string | No | — | Image File |
| `request` | object | No | — | The request value |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"image_file": {
"type": "string",
"description": "Image File"
},
"request": {
"type": "object",
"description": "The request value",
"properties": {
"idempotency_key": {
"type": "string",
"description": "A unique string that identifies this CreateCatalogImage request. Keys can be any valid string but must be unique for every CreateCatalogImage request. See [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information."
},
"object_id": {
"type": "string",
"description": "Unique ID of the `CatalogObject` to attach this `CatalogImage` object to. Leave this field empty to create unattached images, for example if you are building an integration where an image can be attached to catalog items at a later time."
},
"image": {
"type": "object",
"description": "The wrapper object for the catalog entries of a given object type. Depending on the `type` attribute value, a `CatalogObject` instance assumes a type-specific data to yield the corresponding type of catalog object. For example, if `type=ITEM`, the `CatalogObject` instance must have the ITEM-specific data set on the `item_data` attribute. The resulting `CatalogObject` instance is also a `CatalogItem` instance. In general, if `type=`, the `CatalogObject` instance must have the ``-specific data set on the `_data` attribute. The resulting `CatalogObject` instance is also a `Catalog` instance. For a more detailed discussion of the Catalog data model, please see the [Design a Catalog](https://developer.squareup.com/docs/catalog-api/design-a-catalog) guide."
},
"is_primary": {
"type": "boolean",
"description": "If this is set to `true`, the image created will be the primary, or first image of the object referenced by `object_id`. If the `CatalogObject` already has a primary `CatalogImage`, setting this field to `true` will replace the primary image. If this is set to `false` and you use the Square API version 2021-12-15 or later, the image id will be appended to the list of `image_ids` on the object. With Square API version 2021-12-15 or later, the default value is `false`. Otherwise, the effective default value is `true`."
}
},
"required": [
"idempotency_key",
"image"
]
}
},
"required": [
"PCID"
]
}
```
***
## square\_catalog\_create\_order
CreateOrder
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `idempotency_key` | string | No | — | A value you specify that uniquely identifies this order among orders you have created. If you are unsure whether a particular order was created successfully, you can try it again with the same idempotency key without worrying about creating duplicate orders. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). |
| `order` | object | No | — | Contains all information related to a single order to process with Square, including line items that specify the products to purchase. `Order` objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"idempotency_key": {
"type": "string",
"description": "A value you specify that uniquely identifies this order among orders you have created. If you are unsure whether a particular order was created successfully, you can try it again with the same idempotency key without worrying about creating duplicate orders. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
},
"order": {
"type": "object",
"description": "Contains all information related to a single order to process with Square, including line items that specify the products to purchase. `Order` objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.",
"properties": {
"id": {
"type": "string",
"description": "The order's unique ID."
},
"location_id": {
"type": "string",
"description": "The ID of the seller location that this order is associated with."
},
"reference_id": {
"type": "string",
"description": "A client-specified ID to associate an entity in another system with this order."
},
"source": {
"type": "object",
"description": "Represents the origination details of an order."
},
"customer_id": {
"type": "string",
"description": "The ID of the [customer](entity:Customer) associated with the order. You should specify a `customer_id` on the order (or the payment) to ensure that transactions are reliably linked to customers. Omitting this field might result in the creation of new [instant profiles](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles)."
},
"line_items": {
"type": "array",
"items": {
"type": "object"
},
"description": "The line items included in the order."
},
"taxes": {
"type": "array",
"items": {
"type": "object"
},
"description": "The list of all taxes associated with the order. Taxes can be scoped to either `ORDER` or `LINE_ITEM`. For taxes with `LINE_ITEM` scope, an `OrderLineItemAppliedTax` must be added to each line item that the tax applies to. For taxes with `ORDER` scope, the server generates an `OrderLineItemAppliedTax` for every line item. On reads, each tax in the list includes the total amount of that tax applied to the order. __IMPORTANT__: If `LINE_ITEM` scope is set on any taxes in this field, using the deprecated `line_items.taxes` field results in an error. Use `line_items.applied_taxes` instead."
},
"discounts": {
"type": "array",
"items": {
"type": "object"
},
"description": "The list of all discounts associated with the order. Discounts can be scoped to either `ORDER` or `LINE_ITEM`. For discounts scoped to `LINE_ITEM`, an `OrderLineItemAppliedDiscount` must be added to each line item that the discount applies to. For discounts with `ORDER` scope, the server generates an `OrderLineItemAppliedDiscount` for every line item. __IMPORTANT__: If `LINE_ITEM` scope is set on any discounts in this field, using the deprecated `line_items.discounts` field results in an error. Use `line_items.applied_discounts` instead."
},
"service_charges": {
"type": "array",
"items": {
"type": "object"
},
"description": "A list of service charges applied to the order."
},
"fulfillments": {
"type": "array",
"items": {
"type": "object"
},
"description": "Details about order fulfillment. Orders can only be created with at most one fulfillment. However, orders returned by the API might contain multiple fulfillments."
},
"returns": {
"type": "array",
"items": {
"type": "object"
},
"description": "A collection of items from sale orders being returned in this one. Normally part of an itemized return or exchange. There is exactly one `Return` object per sale `Order` being referenced."
},
"return_amounts": {
"type": "object",
"description": "A collection of various money amounts."
},
"net_amounts": {
"type": "object",
"description": "A collection of various money amounts."
},
"rounding_adjustment": {
"type": "object",
"description": "A rounding adjustment of the money being returned. Commonly used to apply cash rounding when the minimum unit of the account is smaller than the lowest physical denomination of the currency."
},
"tenders": {
"type": "array",
"items": {
"type": "object"
},
"description": "The tenders that were used to pay for the order."
},
"refunds": {
"type": "array",
"items": {
"type": "object"
},
"description": "The refunds that are part of this order."
},
"metadata": {
"type": "object",
"description": "Application-defined data attached to this order. Metadata fields are intended to store descriptive references or associations with an entity in another system or store brief information about the object. Square does not process this field; it only stores and returns it in relevant API calls. Do not use metadata to store any sensitive information (such as personally identifiable information or card details). Keys written by applications must be 60 characters or less and must be in the character set `[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a ':' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata)."
},
"created_at": {
"type": "string",
"description": "The timestamp for when the order was created, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")."
},
"updated_at": {
"type": "string",
"description": "The timestamp for when the order was last updated, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")."
},
"closed_at": {
"type": "string",
"description": "The timestamp for when the order reached a terminal [state](entity:OrderState), in RFC 3339 format (for example \"2016-09-04T23:59:33.123Z\")."
},
"state": {
"type": "string",
"description": "The state of the order.",
"enum": [
"OPEN",
"COMPLETED",
"CANCELED",
"DRAFT"
]
},
"version": {
"type": "integer",
"description": "The version number, which is incremented each time an update is committed to the order. Orders not created through the API do not include a version number and therefore cannot be updated. [Read more about working with versions](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders)."
},
"total_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"total_tax_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"total_discount_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"total_tip_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"total_service_charge_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"ticket_name": {
"type": "string",
"description": "A short-term identifier for the order (such as a customer first name, table number, or auto-generated order number that resets daily)."
},
"pricing_options": {
"type": "object",
"description": "Pricing options for an order. The options affect how the order's price is calculated. They can be used, for example, to apply automatic price adjustments that are based on preconfigured [pricing rules](entity:CatalogPricingRule)."
},
"rewards": {
"type": "array",
"items": {
"type": "object"
},
"description": "A set-like list of Rewards that have been added to the Order."
},
"net_amount_due_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
}
},
"required": [
"location_id"
]
}
},
"required": [
"PCID"
]
}
```
***
## square\_catalog\_create\_order\_custom\_attribute\_definition
CreateOrderCustomAttributeDefinition
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `custom_attribute_definition` | object | Yes | — | Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute. |
| `idempotency_key` | string | No | — | A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"custom_attribute_definition": {
"type": "object",
"description": "Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.",
"properties": {
"key": {
"type": "string",
"description": "The identifier of the custom attribute definition and its corresponding custom attributes. This value can be a simple key, which is the key that is provided when the custom attribute definition is created, or a qualified key, if the requesting application is not the definition owner. The qualified key consists of the application ID of the custom attribute definition owner followed by the simple key that was provided when the definition was created. It has the format application_id:simple key. The value for a simple key can contain up to 60 alphanumeric characters, periods (.), underscores (_), and hyphens (-). This field can not be changed after the custom attribute definition is created. This field is required when creating a definition and must be unique per application, seller, and resource type."
},
"schema": {
"type": "object",
"description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information, see [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition."
},
"name": {
"type": "string",
"description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must be unique within the seller and application pair. This field is required if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`."
},
"description": {
"type": "string",
"description": "Seller-oriented description of the custom attribute definition, including any constraints that the seller should observe. May be displayed as a tooltip in Square UIs. This field is required if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`."
},
"visibility": {
"type": "string",
"description": "The level of permission that a seller or other applications requires to view this custom attribute definition. The `Visibility` field controls who can read and write the custom attribute values and custom attribute definition.",
"enum": [
"VISIBILITY_HIDDEN",
"VISIBILITY_READ_ONLY",
"VISIBILITY_READ_WRITE_VALUES"
]
},
"version": {
"type": "integer",
"description": "Read only. The current version of the custom attribute definition. The value is incremented each time the custom attribute definition is updated. When updating a custom attribute definition, you can provide this field and specify the current version of the custom attribute definition to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency). On writes, this field must be set to the latest version. Stale writes are rejected. This field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads, see [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview)."
},
"updated_at": {
"type": "string",
"description": "The timestamp that indicates when the custom attribute definition was created or most recently updated, in RFC 3339 format."
},
"created_at": {
"type": "string",
"description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format."
}
}
},
"idempotency_key": {
"type": "string",
"description": "A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
}
},
"required": [
"PCID",
"custom_attribute_definition"
]
}
```
***
## square\_catalog\_delete\_object
DeleteCatalogObject
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `object_id` | string | Yes | — | The ID of the catalog object 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 catalog item will delete its catalog item variations). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"object_id": {
"type": "string",
"description": "The ID of the catalog object 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 catalog item will delete its catalog item variations)."
}
},
"required": [
"PCID",
"object_id"
]
}
```
***
## square\_catalog\_delete\_order\_custom\_attribute
DeleteOrderCustomAttribute
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ---------------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `order_id` | string | Yes | — | The ID of the target order. |
| `custom_attribute_key` | string | Yes | — | The key of the custom attribute to delete. This key must match the key of an existing custom attribute definition. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"order_id": {
"type": "string",
"description": "The ID of the target [order](entity:Order)."
},
"custom_attribute_key": {
"type": "string",
"description": "The key of the custom attribute to delete. This key must match the key of an existing custom attribute definition."
}
},
"required": [
"PCID",
"order_id",
"custom_attribute_key"
]
}
```
***
## square\_catalog\_delete\_order\_custom\_attribute\_definition
DeleteOrderCustomAttributeDefinition
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ----------------------------------------------------- |
| `key` | string | Yes | — | The key of the custom attribute definition to delete. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"key": {
"type": "string",
"description": "The key of the custom attribute definition to delete."
}
},
"required": [
"PCID",
"key"
]
}
```
***
## square\_catalog\_info
CatalogInfo
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
}
},
"required": [
"PCID"
]
}
```
***
## square\_catalog\_list\_catalog
ListCatalog
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cursor` | string | No | — | The pagination cursor returned in the previous response. Leave unset for an initial request. The page size is currently set to be 100. See [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information. |
| `types` | string | No | — | An optional case-insensitive, comma-separated list of object types to retrieve. The valid values are defined in the CatalogObjectType enum, for example, `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`, `MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc. If this is unspecified, the operation returns objects of all the top level types at the version of the Square API used to make the request. Object types that are nested onto other object types are not included in the defaults. At the current API version the default object types are: ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER\_LIST, PRICING\_RULE, PRODUCT\_SET, TIME\_PERIOD, MEASUREMENT\_UNIT, SUBSCRIPTION\_PLAN, ITEM\_OPTION, CUSTOM\_ATTRIBUTE\_DEFINITION, QUICK\_AMOUNT\_SETTINGS. |
| `catalog_version` | integer | No | — | The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the CatalogObjects' `version` attribute. If not included, results will be from the current version of the catalog. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"cursor": {
"type": "string",
"description": "The pagination cursor returned in the previous response. Leave unset for an initial request. The page size is currently set to be 100. See [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information."
},
"types": {
"type": "string",
"description": "An optional case-insensitive, comma-separated list of object types to retrieve. The valid values are defined in the [CatalogObjectType](entity:CatalogObjectType) enum, for example, `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`, `MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc. If this is unspecified, the operation returns objects of all the top level types at the version of the Square API used to make the request. Object types that are nested onto other object types are not included in the defaults. At the current API version the default object types are: ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS."
},
"catalog_version": {
"type": "integer",
"description": "The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the [CatalogObject](entity:CatalogObject)s' `version` attribute. If not included, results will be from the current version of the catalog."
}
},
"required": [
"PCID"
]
}
```
***
## square\_catalog\_list\_order\_custom\_attribute\_definitions
ListOrderCustomAttributeDefinitions
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `visibility_filter` | string | No | — | Requests that all of the custom attributes be returned, or only those that are read-only or read-write. |
| `cursor` | string | No | — | The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
| `limit` | integer | No | — | The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"visibility_filter": {
"type": "string",
"description": "Requests that all of the custom attributes be returned, or only those that are read-only or read-write.",
"enum": [
"ALL",
"READ",
"READ_WRITE"
]
},
"cursor": {
"type": "string",
"description": "The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)."
},
"limit": {
"type": "integer",
"description": "The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)."
}
},
"required": [
"PCID"
]
}
```
***
## square\_catalog\_list\_order\_custom\_attributes
ListOrderCustomAttributes
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order_id` | string | Yes | — | The ID of the target order. |
| `visibility_filter` | string | No | — | Requests that all of the custom attributes be returned, or only those that are read-only or read-write. |
| `cursor` | string | No | — | The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
| `limit` | integer | No | — | The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
| `with_definitions` | boolean | No | — | Indicates whether to return the custom attribute definition in the `definition` field of each custom attribute. Set this parameter to `true` to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is `false`. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"order_id": {
"type": "string",
"description": "The ID of the target [order](entity:Order)."
},
"visibility_filter": {
"type": "string",
"description": "Requests that all of the custom attributes be returned, or only those that are read-only or read-write.",
"enum": [
"ALL",
"READ",
"READ_WRITE"
]
},
"cursor": {
"type": "string",
"description": "The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)."
},
"limit": {
"type": "integer",
"description": "The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)."
},
"with_definitions": {
"type": "boolean",
"description": "Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of each custom attribute. Set this parameter to `true` to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is `false`."
}
},
"required": [
"PCID",
"order_id"
]
}
```
***
## square\_catalog\_pay\_order
PayOrder
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `order_id` | string | Yes | — | The ID of the order being paid. | |
| `idempotency_key` | string | Yes | — | A value you specify that uniquely identifies this request among requests you have sent. If you are unsure whether a particular payment request was completed successfully, you can reattempt it with the same idempotency key without worrying about duplicate payments. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency). | |
| `order_version` | integer | null | No | — | The version of the order being paid. If not supplied, the latest version will be paid. |
| `payment_ids` | string\[] | No | — | The IDs of the payments to collect. The payment total must match the order total. | |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"order_id": {
"type": "string",
"description": "The ID of the order being paid."
},
"idempotency_key": {
"type": "string",
"description": "A value you specify that uniquely identifies this request among requests you have sent. If you are unsure whether a particular payment request was completed successfully, you can reattempt it with the same idempotency key without worrying about duplicate payments. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency)."
},
"order_version": {
"type": [
"integer",
"null"
],
"description": "The version of the order being paid. If not supplied, the latest version will be paid."
},
"payment_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The IDs of the [payments](entity:Payment) to collect. The payment total must match the order total."
}
},
"required": [
"PCID",
"order_id",
"idempotency_key"
]
}
```
***
## square\_catalog\_retrieve\_catalog\_object
RetrieveCatalogObject
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object_id` | string | Yes | — | The object ID of any type of catalog objects to be retrieved. |
| `include_related_objects` | boolean | No | — | If `true`, the response will include additional objects that are related to the requested objects. Related objects are defined as any objects referenced by ID by the results in the `objects` field of the response. These objects are put in the `related_objects` field. Setting this to `true` is helpful when the objects are needed for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example, if the `objects` field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects 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. Default value: `false` |
| `catalog_version` | integer | No | — | Requests objects as of a specific version of the catalog. This allows you to retrieve historical versions of objects. The value to retrieve a specific version of an object can be found in the version field of CatalogObjects. If not included, results will be from the current version of the catalog. |
| `include_category_path_to_root` | boolean | No | — | Specifies whether or not to include the `path_to_root` list for each returned category instance. The `path_to_root` list consists of `CategoryPathToRootNode` objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the `path_to_root` list is empty and is not returned in the response payload. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"object_id": {
"type": "string",
"description": "The object ID of any type of catalog objects to be retrieved."
},
"include_related_objects": {
"type": "boolean",
"description": "If `true`, the response will include additional objects that are related to the requested objects. Related objects are defined as any objects referenced by ID by the results in the `objects` field of the response. These objects are put in the `related_objects` field. Setting this to `true` is helpful when the objects are needed for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example, if the `objects` field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects 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. Default value: `false`"
},
"catalog_version": {
"type": "integer",
"description": "Requests objects as of a specific version of the catalog. This allows you to retrieve historical versions of objects. The value to retrieve a specific version of an object can be found in the version field of [CatalogObject](entity:CatalogObject)s. If not included, results will be from the current version of the catalog."
},
"include_category_path_to_root": {
"type": "boolean",
"description": "Specifies whether or not to include the `path_to_root` list for each returned category instance. The `path_to_root` list consists of `CategoryPathToRootNode` objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the `path_to_root` list is empty and is not returned in the response payload."
}
},
"required": [
"PCID",
"object_id"
]
}
```
***
## square\_catalog\_retrieve\_inventory\_adjustment
RetrieveInventoryAdjustment
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------------- | ------ | -------- | ------- | ------------------------------------------ |
| `adjustment_id` | string | Yes | — | ID of the InventoryAdjustment to retrieve. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"adjustment_id": {
"type": "string",
"description": "ID of the [InventoryAdjustment](entity:InventoryAdjustment) to retrieve."
}
},
"required": [
"PCID",
"adjustment_id"
]
}
```
***
## square\_catalog\_retrieve\_inventory\_count
RetrieveInventoryCount
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `catalog_object_id` | string | Yes | — | ID of the CatalogObject to retrieve. |
| `location_ids` | string | No | — | The Location IDs to look up as a comma-separated list. An empty list queries all locations. |
| `cursor` | string | No | — | 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 the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"catalog_object_id": {
"type": "string",
"description": "ID of the [CatalogObject](entity:CatalogObject) to retrieve."
},
"location_ids": {
"type": "string",
"description": "The [Location](entity:Location) IDs to look up as a comma-separated list. An empty list queries all locations."
},
"cursor": {
"type": "string",
"description": "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 the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information."
}
},
"required": [
"PCID",
"catalog_object_id"
]
}
```
***
## square\_catalog\_retrieve\_inventory\_physical\_count
RetrieveInventoryPhysicalCount
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------- | ------ | -------- | ------- | --------------------------------------------- |
| `physical_count_id` | string | Yes | — | ID of the InventoryPhysicalCount to retrieve. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"physical_count_id": {
"type": "string",
"description": "ID of the [InventoryPhysicalCount](entity:InventoryPhysicalCount) to retrieve."
}
},
"required": [
"PCID",
"physical_count_id"
]
}
```
***
## square\_catalog\_retrieve\_inventory\_transfer
RetrieveInventoryTransfer
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | ------ | -------- | ------- | ---------------------------------------- |
| `transfer_id` | string | Yes | — | ID of the InventoryTransfer to retrieve. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"transfer_id": {
"type": "string",
"description": "ID of the [InventoryTransfer](entity:InventoryTransfer) to retrieve."
}
},
"required": [
"PCID",
"transfer_id"
]
}
```
***
## square\_catalog\_retrieve\_order
RetrieveOrder
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ---------- | ------ | -------- | ------- | -------------------------------- |
| `order_id` | string | Yes | — | The ID of the order to retrieve. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"order_id": {
"type": "string",
"description": "The ID of the order to retrieve."
}
},
"required": [
"PCID",
"order_id"
]
}
```
***
## square\_catalog\_retrieve\_order\_custom\_attribute
RetrieveOrderCustomAttribute
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ---------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order_id` | string | Yes | — | The ID of the target order. |
| `custom_attribute_key` | string | Yes | — | The key of the custom attribute to retrieve. This key must match the key of an existing custom attribute definition. |
| `version` | integer | No | — | To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control, include this optional field and specify the current version of the custom attribute. |
| `with_definition` | boolean | No | — | Indicates whether to return the custom attribute definition in the `definition` field of each custom attribute. Set this parameter to `true` to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is `false`. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"order_id": {
"type": "string",
"description": "The ID of the target [order](entity:Order)."
},
"custom_attribute_key": {
"type": "string",
"description": "The key of the custom attribute to retrieve. This key must match the key of an existing custom attribute definition."
},
"version": {
"type": "integer",
"description": "To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control, include this optional field and specify the current version of the custom attribute."
},
"with_definition": {
"type": "boolean",
"description": "Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of each custom attribute. Set this parameter to `true` to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is `false`."
}
},
"required": [
"PCID",
"order_id",
"custom_attribute_key"
]
}
```
***
## square\_catalog\_retrieve\_order\_custom\_attribute\_definition
RetrieveOrderCustomAttributeDefinition
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key` | string | Yes | — | The key of the custom attribute definition to retrieve. |
| `version` | integer | No | — | To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control, include this optional field and specify the current version of the custom attribute. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"key": {
"type": "string",
"description": "The key of the custom attribute definition to retrieve."
},
"version": {
"type": "integer",
"description": "To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control, include this optional field and specify the current version of the custom attribute."
}
},
"required": [
"PCID",
"key"
]
}
```
***
## square\_catalog\_search\_catalog\_items
SearchCatalogItems
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------------------- | --------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `archived_state` | string | No | — | Defines the values for the `archived_state` query expression used in SearchCatalogItems to return the archived, not archived or either type of catalog items. |
| `category_ids` | string\[] | No | — | The category id query expression to return items containing the specified category IDs. |
| `cursor` | string | No | — | The pagination token, returned in the previous response, used to fetch the next batch of pending results. |
| `custom_attribute_filters` | object\[] | No | — | The customer-attribute filter to return items or item variations matching the specified custom attribute expressions. A maximum number of 10 custom attribute expressions are supported in a single call to the SearchCatalogItems endpoint. |
| `enabled_location_ids` | string\[] | No | — | The enabled-location query expression to return items and item variations having specified enabled locations. |
| `limit` | integer | No | — | The maximum number of results to return per page. The default value is 100. |
| `product_types` | string\[] | No | — | The product types query expression to return items or item variations having the specified product types. |
| `sort_order` | string | No | — | The order (e.g., chronological or alphabetical) in which results from a request are returned. |
| `stock_levels` | string\[] | No | — | The stock-level query expression to return item variations with the specified stock levels. See SearchCatalogItemsRequestStockLevel for possible values |
| `text_filter` | string | No | — | The text filter expression to return items or item variations containing specified text in the `name`, `description`, or `abbreviation` attribute value of an item, or in the `name`, `sku`, or `upc` attribute value of an item variation. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"archived_state": {
"type": "string",
"description": "Defines the values for the `archived_state` query expression used in [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) to return the archived, not archived or either type of catalog items.",
"enum": [
"ARCHIVED_STATE_NOT_ARCHIVED",
"ARCHIVED_STATE_ARCHIVED",
"ARCHIVED_STATE_ALL"
]
},
"category_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The category id query expression to return items containing the specified category IDs."
},
"cursor": {
"type": "string",
"description": "The pagination token, returned in the previous response, used to fetch the next batch of pending results."
},
"custom_attribute_filters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"custom_attribute_definition_id": {
"type": "string",
"description": "A query expression to filter items or item variations by matching their custom attributes' `custom_attribute_definition_id` property value against the the specified id. Exactly one of `custom_attribute_definition_id` or `key` must be specified."
},
"key": {
"type": "string",
"description": "A query expression to filter items or item variations by matching their custom attributes' `key` property value against the specified key. Exactly one of `custom_attribute_definition_id` or `key` must be specified."
},
"string_filter": {
"type": "string",
"description": "A query expression to filter items or item variations by matching their custom attributes' `string_value` property value against the specified text. Exactly one of `string_filter`, `number_filter`, `selection_uids_filter`, or `bool_filter` must be specified."
},
"number_filter": {
"type": "object",
"description": "The range of a number value between the specified lower and upper bounds."
},
"selection_uids_filter": {
"type": "array",
"items": {
"type": "string"
},
"description": "A query expression to filter items or item variations by matching their custom attributes' `selection_uid_values` values against the specified selection uids. Exactly one of `string_filter`, `number_filter`, `selection_uids_filter`, or `bool_filter` must be specified."
},
"bool_filter": {
"type": "boolean",
"description": "A query expression to filter items or item variations by matching their custom attributes' `boolean_value` property values against the specified Boolean expression. Exactly one of `string_filter`, `number_filter`, `selection_uids_filter`, or `bool_filter` must be specified."
}
}
},
"description": "The customer-attribute filter to return items or item variations matching the specified custom attribute expressions. A maximum number of 10 custom attribute expressions are supported in a single call to the [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) endpoint."
},
"enabled_location_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The enabled-location query expression to return items and item variations having specified enabled locations."
},
"limit": {
"type": "integer",
"description": "The maximum number of results to return per page. The default value is 100."
},
"product_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"REGULAR",
"GIFT_CARD",
"APPOINTMENTS_SERVICE",
"FOOD_AND_BEV",
"EVENT",
"DIGITAL",
"DONATION",
"LEGACY_SQUARE_ONLINE_SERVICE",
"LEGACY_SQUARE_ONLINE_MEMBERSHIP"
]
},
"description": "The product types query expression to return items or item variations having the specified product types."
},
"sort_order": {
"type": "string",
"description": "The order (e.g., chronological or alphabetical) in which results from a request are returned.",
"enum": [
"DESC",
"ASC"
]
},
"stock_levels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"OUT",
"LOW"
]
},
"description": "The stock-level query expression to return item variations with the specified stock levels. See [SearchCatalogItemsRequestStockLevel](#type-searchcatalogitemsrequeststocklevel) for possible values"
},
"text_filter": {
"type": "string",
"description": "The text filter expression to return items or item variations containing specified text in the `name`, `description`, or `abbreviation` attribute value of an item, or in the `name`, `sku`, or `upc` attribute value of an item variation."
}
},
"required": [
"PCID"
]
}
```
***
## square\_catalog\_search\_catalog\_objects
SearchCatalogObjects
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------------------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `begin_time` | string | No | — | Return objects modified after this [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates), 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. |
| `cursor` | string | No | — | The pagination cursor returned in the previous response. Leave unset for an initial request. See [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information. |
| `include_category_path_to_root` | boolean | No | — | Specifies whether or not to include the `path_to_root` list for each returned category instance. The `path_to_root` list consists of `CategoryPathToRootNode` objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the `path_to_root` list is empty and is not returned in the response payload. If `include_category_path_to_root` is `true`, then the `include_deleted_objects` request parameter must be `false`. Both properties cannot be `true` at the same time. |
| `include_deleted_objects` | boolean | No | — | If `true`, deleted objects will be included in the results. Defaults to `false`. Deleted objects will have their `is_deleted` field set to `true`. If `include_deleted_objects` is `true`, then the `include_category_path_to_root` request parameter must be `false`. Both properties cannot be `true` at the same time. |
| `include_related_objects` | boolean | No | — | If `true`, the response will include additional objects that are related to the requested objects. Related objects are objects that are referenced by object ID by the objects in the response. This is helpful if the objects are being fetched for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example: If the `objects` field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects 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. Default value: `false` |
| `limit` | integer | No | — | 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. |
| `object_types` | string\[] | No | — | The desired set of object types to appear in the search results. If this is unspecified, the operation returns objects of all the top level types at the version of the Square API used to make the request. Object types that are nested onto other object types are not included in the defaults. At the current API version the default object types are: ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER\_LIST, PRICING\_RULE, PRODUCT\_SET, TIME\_PERIOD, MEASUREMENT\_UNIT, SUBSCRIPTION\_PLAN, ITEM\_OPTION, CUSTOM\_ATTRIBUTE\_DEFINITION, QUICK\_AMOUNT\_SETTINGS. Note that if you wish for the query to return objects belonging to nested types (i.e., COMPONENT, IMAGE, ITEM\_OPTION\_VAL, ITEM\_VARIATION, or MODIFIER), you must explicitly include all the types of interest in this field. |
| `query` | object | No | — | A query composed of one or more different types of filters to narrow the scope of targeted objects when calling the `SearchCatalogObjects` endpoint. Although a query can have multiple filters, only certain query types can be combined per call to SearchCatalogObjects. Any combination of the following types may be used together: - exact\_query - prefix\_query - range\_query - sorted\_attribute\_query - text\_query All other query types cannot be combined with any others. When a query filter is based on an attribute, the attribute must be searchable. Searchable attributes are listed as follows, along their parent types that can be searched for with applicable query filters. Searchable attribute and objects queryable by searchable attributes: - `name`: `CatalogItem`, `CatalogItemVariation`, `CatalogCategory`, `CatalogTax`, `CatalogDiscount`, `CatalogModifier`, `CatalogModifierList`, `CatalogItemOption`, `CatalogItemOptionValue` - `description`: `CatalogItem`, `CatalogItemOptionValue` - `abbreviation`: `CatalogItem` - `upc`: `CatalogItemVariation` - `sku`: `CatalogItemVariation` - `caption`: `CatalogImage` - `display_name`: `CatalogItemOption` For example, to search for CatalogItem objects by searchable attributes, you can use the `"name"`, `"description"`, or `"abbreviation"` attribute in an applicable query filter. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"begin_time": {
"type": "string",
"description": "Return objects modified after this [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates), 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."
},
"cursor": {
"type": "string",
"description": "The pagination cursor returned in the previous response. Leave unset for an initial request. See [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information."
},
"include_category_path_to_root": {
"type": "boolean",
"description": "Specifies whether or not to include the `path_to_root` list for each returned category instance. The `path_to_root` list consists of `CategoryPathToRootNode` objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the `path_to_root` list is empty and is not returned in the response payload. If `include_category_path_to_root` is `true`, then the `include_deleted_objects` request parameter must be `false`. Both properties cannot be `true` at the same time."
},
"include_deleted_objects": {
"type": "boolean",
"description": "If `true`, deleted objects will be included in the results. Defaults to `false`. Deleted objects will have their `is_deleted` field set to `true`. If `include_deleted_objects` is `true`, then the `include_category_path_to_root` request parameter must be `false`. Both properties cannot be `true` at the same time."
},
"include_related_objects": {
"type": "boolean",
"description": "If `true`, the response will include additional objects that are related to the requested objects. Related objects are objects that are referenced by object ID by the objects in the response. This is helpful if the objects are being fetched for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example: If the `objects` field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects 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. Default value: `false`"
},
"limit": {
"type": "integer",
"description": "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."
},
"object_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ITEM",
"IMAGE",
"CATEGORY",
"ITEM_VARIATION",
"TAX",
"DISCOUNT",
"MODIFIER_LIST",
"MODIFIER",
"PRICING_RULE",
"PRODUCT_SET",
"TIME_PERIOD",
"MEASUREMENT_UNIT",
"SUBSCRIPTION_PLAN_VARIATION",
"ITEM_OPTION",
"ITEM_OPTION_VAL",
"CUSTOM_ATTRIBUTE_DEFINITION",
"QUICK_AMOUNTS_SETTINGS",
"SUBSCRIPTION_PLAN",
"AVAILABILITY_PERIOD"
]
},
"description": "The desired set of object types to appear in the search results. If this is unspecified, the operation returns objects of all the top level types at the version of the Square API used to make the request. Object types that are nested onto other object types are not included in the defaults. At the current API version the default object types are: ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. Note that if you wish for the query to return objects belonging to nested types (i.e., COMPONENT, IMAGE, ITEM_OPTION_VAL, ITEM_VARIATION, or MODIFIER), you must explicitly include all the types of interest in this field."
},
"query": {
"type": "object",
"description": "A query composed of one or more different types of filters to narrow the scope of targeted objects when calling the `SearchCatalogObjects` endpoint. Although a query can have multiple filters, only certain query types can be combined per call to [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects). Any combination of the following types may be used together: - [exact_query](entity:CatalogQueryExact) - [prefix_query](entity:CatalogQueryPrefix) - [range_query](entity:CatalogQueryRange) - [sorted_attribute_query](entity:CatalogQuerySortedAttribute) - [text_query](entity:CatalogQueryText) All other query types cannot be combined with any others. When a query filter is based on an attribute, the attribute must be searchable. Searchable attributes are listed as follows, along their parent types that can be searched for with applicable query filters. Searchable attribute and objects queryable by searchable attributes: - `name`: `CatalogItem`, `CatalogItemVariation`, `CatalogCategory`, `CatalogTax`, `CatalogDiscount`, `CatalogModifier`, `CatalogModifierList`, `CatalogItemOption`, `CatalogItemOptionValue` - `description`: `CatalogItem`, `CatalogItemOptionValue` - `abbreviation`: `CatalogItem` - `upc`: `CatalogItemVariation` - `sku`: `CatalogItemVariation` - `caption`: `CatalogImage` - `display_name`: `CatalogItemOption` For example, to search for [CatalogItem](entity:CatalogItem) objects by searchable attributes, you can use the `\"name\"`, `\"description\"`, or `\"abbreviation\"` attribute in an applicable query filter.",
"properties": {
"sorted_attribute_query": {
"type": "object",
"description": "The query expression to specify the key to sort search results."
},
"exact_query": {
"type": "object",
"description": "The query filter to return the search result by exact match of the specified attribute name and value."
},
"set_query": {
"type": "object",
"description": "The query filter to return the search result(s) by exact match of the specified `attribute_name` and any of the `attribute_values`."
},
"prefix_query": {
"type": "object",
"description": "The query filter to return the search result whose named attribute values are prefixed by the specified attribute value."
},
"range_query": {
"type": "object",
"description": "The query filter to return the search result whose named attribute values fall between the specified range."
},
"text_query": {
"type": "object",
"description": "The query filter to return the search result whose searchable attribute values contain all of the specified keywords or tokens, independent of the token order or case."
},
"items_for_tax_query": {
"type": "object",
"description": "The query filter to return the items containing the specified tax IDs."
},
"items_for_modifier_list_query": {
"type": "object",
"description": "The query filter to return the items containing the specified modifier list IDs."
},
"items_for_item_options_query": {
"type": "object",
"description": "The query filter to return the items containing the specified item option IDs."
},
"item_variations_for_item_option_values_query": {
"type": "object",
"description": "The query filter to return the item variations containing the specified item option value IDs."
}
}
}
},
"required": [
"PCID"
]
}
```
***
## square\_catalog\_search\_orders
SearchOrders
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ---------------- | --------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cursor` | string | No | — | A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). |
| `limit` | integer | No | — | The maximum number of results to be returned in a single page. Default: `500` Max: `1000` |
| `location_ids` | string\[] | No | — | The location IDs for the orders to query. All locations must belong to the same merchant. Max: 10 location IDs. |
| `query` | object | No | — | Contains query criteria for the search. |
| `return_entries` | boolean | No | — | A Boolean that controls the format of the search results. If `true`, `SearchOrders` returns OrderEntry objects. If `false`, `SearchOrders` returns complete order objects. Default: `false`. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"cursor": {
"type": "string",
"description": "A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)."
},
"limit": {
"type": "integer",
"description": "The maximum number of results to be returned in a single page. Default: `500` Max: `1000`"
},
"location_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The location IDs for the orders to query. All locations must belong to the same merchant. Max: 10 location IDs."
},
"query": {
"type": "object",
"description": "Contains query criteria for the search.",
"properties": {
"filter": {
"type": "object",
"description": "Filtering criteria to use for a `SearchOrders` request. Multiple filters are ANDed together."
},
"sort": {
"type": "object",
"description": "Sorting criteria for a `SearchOrders` request. Results can only be sorted by a timestamp field."
}
}
},
"return_entries": {
"type": "boolean",
"description": "A Boolean that controls the format of the search results. If `true`, `SearchOrders` returns [OrderEntry](entity:OrderEntry) objects. If `false`, `SearchOrders` returns complete order objects. Default: `false`."
}
},
"required": [
"PCID"
]
}
```
***
## square\_catalog\_update\_catalog\_image
UpdateCatalogImage
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------ | ------ | -------- | ------- | -------------------------------------------------------------------------- |
| `image_id` | string | Yes | — | The ID of the `CatalogImage` object to update the encapsulated image file. |
| `image_file` | string | No | — | Image File |
| `request` | object | No | — | The request value |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"image_id": {
"type": "string",
"description": "The ID of the `CatalogImage` object to update the encapsulated image file."
},
"image_file": {
"type": "string",
"description": "Image File"
},
"request": {
"type": "object",
"description": "The request value",
"properties": {
"idempotency_key": {
"type": "string",
"description": "A unique string that identifies this UpdateCatalogImage request. Keys can be any valid string but must be unique for every UpdateCatalogImage request. See [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information."
}
},
"required": [
"idempotency_key"
]
}
},
"required": [
"PCID",
"image_id"
]
}
```
***
## square\_catalog\_update\_item\_modifier\_lists
UpdateItemModifierLists
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------------------------- | --------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `item_ids` | string\[] | Yes | — | The IDs of the catalog items associated with the CatalogModifierList objects being updated. |
| `modifier_lists_to_disable` | string\[] | No | — | The IDs of the CatalogModifierList objects to disable for the CatalogItem. At least one of `modifier_lists_to_enable` or `modifier_lists_to_disable` must be specified. |
| `modifier_lists_to_enable` | string\[] | No | — | The IDs of the CatalogModifierList objects to enable for the CatalogItem. At least one of `modifier_lists_to_enable` or `modifier_lists_to_disable` must be specified. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"item_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The IDs of the catalog items associated with the CatalogModifierList objects being updated."
},
"modifier_lists_to_disable": {
"type": "array",
"items": {
"type": "string"
},
"description": "The IDs of the CatalogModifierList objects to disable for the CatalogItem. At least one of `modifier_lists_to_enable` or `modifier_lists_to_disable` must be specified."
},
"modifier_lists_to_enable": {
"type": "array",
"items": {
"type": "string"
},
"description": "The IDs of the CatalogModifierList objects to enable for the CatalogItem. At least one of `modifier_lists_to_enable` or `modifier_lists_to_disable` must be specified."
}
},
"required": [
"PCID",
"item_ids"
]
}
```
***
## square\_catalog\_update\_item\_taxes
UpdateItemTaxes
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------ | --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `item_ids` | string\[] | Yes | — | IDs for the CatalogItems associated with the CatalogTax objects being updated. No more than 1,000 IDs may be provided. |
| `taxes_to_disable` | string\[] | No | — | IDs of the CatalogTax objects to disable. At least one of `taxes_to_enable` or `taxes_to_disable` must be specified. |
| `taxes_to_enable` | string\[] | No | — | IDs of the CatalogTax objects to enable. At least one of `taxes_to_enable` or `taxes_to_disable` must be specified. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"item_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "IDs for the CatalogItems associated with the CatalogTax objects being updated. No more than 1,000 IDs may be provided."
},
"taxes_to_disable": {
"type": "array",
"items": {
"type": "string"
},
"description": "IDs of the CatalogTax objects to disable. At least one of `taxes_to_enable` or `taxes_to_disable` must be specified."
},
"taxes_to_enable": {
"type": "array",
"items": {
"type": "string"
},
"description": "IDs of the CatalogTax objects to enable. At least one of `taxes_to_enable` or `taxes_to_disable` must be specified."
}
},
"required": [
"PCID",
"item_ids"
]
}
```
***
## square\_catalog\_update\_order
UpdateOrder
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------- | --------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order_id` | string | Yes | — | The ID of the order to update. | |
| `fields_to_clear` | string\[] | No | — | The [dot notation paths](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#identifying-fields-to-delete) fields to clear. For example, `line_items[uid].note`. For more information, see [Deleting fields](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#deleting-fields). | |
| `idempotency_key` | string | null | No | — | A value you specify that uniquely identifies this update request. If you are unsure whether a particular update was applied to an order successfully, you can reattempt it with the same idempotency key without worrying about creating duplicate updates to the order. The latest order version is returned. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). |
| `order` | object | No | — | Contains all information related to a single order to process with Square, including line items that specify the products to purchase. `Order` objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data. | |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"order_id": {
"type": "string",
"description": "The ID of the order to update."
},
"fields_to_clear": {
"type": "array",
"items": {
"type": "string"
},
"description": "The [dot notation paths](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#identifying-fields-to-delete) fields to clear. For example, `line_items[uid].note`. For more information, see [Deleting fields](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#deleting-fields)."
},
"idempotency_key": {
"type": [
"string",
"null"
],
"description": "A value you specify that uniquely identifies this update request. If you are unsure whether a particular update was applied to an order successfully, you can reattempt it with the same idempotency key without worrying about creating duplicate updates to the order. The latest order version is returned. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
},
"order": {
"type": "object",
"description": "Contains all information related to a single order to process with Square, including line items that specify the products to purchase. `Order` objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.",
"properties": {
"id": {
"type": "string",
"description": "The order's unique ID."
},
"location_id": {
"type": "string",
"description": "The ID of the seller location that this order is associated with."
},
"reference_id": {
"type": "string",
"description": "A client-specified ID to associate an entity in another system with this order."
},
"source": {
"type": "object",
"description": "Represents the origination details of an order."
},
"customer_id": {
"type": "string",
"description": "The ID of the [customer](entity:Customer) associated with the order. You should specify a `customer_id` on the order (or the payment) to ensure that transactions are reliably linked to customers. Omitting this field might result in the creation of new [instant profiles](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles)."
},
"line_items": {
"type": "array",
"items": {
"type": "object"
},
"description": "The line items included in the order."
},
"taxes": {
"type": "array",
"items": {
"type": "object"
},
"description": "The list of all taxes associated with the order. Taxes can be scoped to either `ORDER` or `LINE_ITEM`. For taxes with `LINE_ITEM` scope, an `OrderLineItemAppliedTax` must be added to each line item that the tax applies to. For taxes with `ORDER` scope, the server generates an `OrderLineItemAppliedTax` for every line item. On reads, each tax in the list includes the total amount of that tax applied to the order. __IMPORTANT__: If `LINE_ITEM` scope is set on any taxes in this field, using the deprecated `line_items.taxes` field results in an error. Use `line_items.applied_taxes` instead."
},
"discounts": {
"type": "array",
"items": {
"type": "object"
},
"description": "The list of all discounts associated with the order. Discounts can be scoped to either `ORDER` or `LINE_ITEM`. For discounts scoped to `LINE_ITEM`, an `OrderLineItemAppliedDiscount` must be added to each line item that the discount applies to. For discounts with `ORDER` scope, the server generates an `OrderLineItemAppliedDiscount` for every line item. __IMPORTANT__: If `LINE_ITEM` scope is set on any discounts in this field, using the deprecated `line_items.discounts` field results in an error. Use `line_items.applied_discounts` instead."
},
"service_charges": {
"type": "array",
"items": {
"type": "object"
},
"description": "A list of service charges applied to the order."
},
"fulfillments": {
"type": "array",
"items": {
"type": "object"
},
"description": "Details about order fulfillment. Orders can only be created with at most one fulfillment. However, orders returned by the API might contain multiple fulfillments."
},
"returns": {
"type": "array",
"items": {
"type": "object"
},
"description": "A collection of items from sale orders being returned in this one. Normally part of an itemized return or exchange. There is exactly one `Return` object per sale `Order` being referenced."
},
"return_amounts": {
"type": "object",
"description": "A collection of various money amounts."
},
"net_amounts": {
"type": "object",
"description": "A collection of various money amounts."
},
"rounding_adjustment": {
"type": "object",
"description": "A rounding adjustment of the money being returned. Commonly used to apply cash rounding when the minimum unit of the account is smaller than the lowest physical denomination of the currency."
},
"tenders": {
"type": "array",
"items": {
"type": "object"
},
"description": "The tenders that were used to pay for the order."
},
"refunds": {
"type": "array",
"items": {
"type": "object"
},
"description": "The refunds that are part of this order."
},
"metadata": {
"type": "object",
"description": "Application-defined data attached to this order. Metadata fields are intended to store descriptive references or associations with an entity in another system or store brief information about the object. Square does not process this field; it only stores and returns it in relevant API calls. Do not use metadata to store any sensitive information (such as personally identifiable information or card details). Keys written by applications must be 60 characters or less and must be in the character set `[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a ':' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata)."
},
"created_at": {
"type": "string",
"description": "The timestamp for when the order was created, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")."
},
"updated_at": {
"type": "string",
"description": "The timestamp for when the order was last updated, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")."
},
"closed_at": {
"type": "string",
"description": "The timestamp for when the order reached a terminal [state](entity:OrderState), in RFC 3339 format (for example \"2016-09-04T23:59:33.123Z\")."
},
"state": {
"type": "string",
"description": "The state of the order.",
"enum": [
"OPEN",
"COMPLETED",
"CANCELED",
"DRAFT"
]
},
"version": {
"type": "integer",
"description": "The version number, which is incremented each time an update is committed to the order. Orders not created through the API do not include a version number and therefore cannot be updated. [Read more about working with versions](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders)."
},
"total_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"total_tax_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"total_discount_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"total_tip_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"total_service_charge_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"ticket_name": {
"type": "string",
"description": "A short-term identifier for the order (such as a customer first name, table number, or auto-generated order number that resets daily)."
},
"pricing_options": {
"type": "object",
"description": "Pricing options for an order. The options affect how the order's price is calculated. They can be used, for example, to apply automatic price adjustments that are based on preconfigured [pricing rules](entity:CatalogPricingRule)."
},
"rewards": {
"type": "array",
"items": {
"type": "object"
},
"description": "A set-like list of Rewards that have been added to the Order."
},
"net_amount_due_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
}
},
"required": [
"location_id"
]
}
},
"required": [
"PCID",
"order_id"
]
}
```
***
## square\_catalog\_update\_order\_custom\_attribute\_definition
UpdateOrderCustomAttributeDefinition
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key` | string | Yes | — | The key of the custom attribute definition to update. | |
| `custom_attribute_definition` | object | Yes | — | Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute. | |
| `idempotency_key` | string | null | No | — | A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"key": {
"type": "string",
"description": "The key of the custom attribute definition to update."
},
"custom_attribute_definition": {
"type": "object",
"description": "Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.",
"properties": {
"key": {
"type": "string",
"description": "The identifier of the custom attribute definition and its corresponding custom attributes. This value can be a simple key, which is the key that is provided when the custom attribute definition is created, or a qualified key, if the requesting application is not the definition owner. The qualified key consists of the application ID of the custom attribute definition owner followed by the simple key that was provided when the definition was created. It has the format application_id:simple key. The value for a simple key can contain up to 60 alphanumeric characters, periods (.), underscores (_), and hyphens (-). This field can not be changed after the custom attribute definition is created. This field is required when creating a definition and must be unique per application, seller, and resource type."
},
"schema": {
"type": "object",
"description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information, see [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition."
},
"name": {
"type": "string",
"description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must be unique within the seller and application pair. This field is required if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`."
},
"description": {
"type": "string",
"description": "Seller-oriented description of the custom attribute definition, including any constraints that the seller should observe. May be displayed as a tooltip in Square UIs. This field is required if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`."
},
"visibility": {
"type": "string",
"description": "The level of permission that a seller or other applications requires to view this custom attribute definition. The `Visibility` field controls who can read and write the custom attribute values and custom attribute definition.",
"enum": [
"VISIBILITY_HIDDEN",
"VISIBILITY_READ_ONLY",
"VISIBILITY_READ_WRITE_VALUES"
]
},
"version": {
"type": "integer",
"description": "Read only. The current version of the custom attribute definition. The value is incremented each time the custom attribute definition is updated. When updating a custom attribute definition, you can provide this field and specify the current version of the custom attribute definition to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency). On writes, this field must be set to the latest version. Stale writes are rejected. This field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads, see [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview)."
},
"updated_at": {
"type": "string",
"description": "The timestamp that indicates when the custom attribute definition was created or most recently updated, in RFC 3339 format."
},
"created_at": {
"type": "string",
"description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format."
}
}
},
"idempotency_key": {
"type": [
"string",
"null"
],
"description": "A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
}
},
"required": [
"PCID",
"key",
"custom_attribute_definition"
]
}
```
***
## square\_catalog\_upsert\_catalog\_object
UpsertCatalogObject
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `idempotency_key` | string | Yes | — | 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information. |
| `object` | object | Yes | — | The wrapper object for the catalog entries of a given object type. Depending on the `type` attribute value, a `CatalogObject` instance assumes a type-specific data to yield the corresponding type of catalog object. For example, if `type=ITEM`, the `CatalogObject` instance must have the ITEM-specific data set on the `item_data` attribute. The resulting `CatalogObject` instance is also a `CatalogItem` instance. In general, if `type=<OBJECT_TYPE>`, the `CatalogObject` instance must have the `<OBJECT_TYPE>`-specific data set on the `<object_type>_data` attribute. The resulting `CatalogObject` instance is also a `Catalog<ObjectType>` instance. For a more detailed discussion of the Catalog data model, please see the [Design a Catalog](https://developer.squareup.com/docs/catalog-api/design-a-catalog) guide. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"idempotency_key": {
"type": "string",
"description": "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](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information."
},
"object": {
"type": "object",
"description": "The wrapper object for the catalog entries of a given object type. Depending on the `type` attribute value, a `CatalogObject` instance assumes a type-specific data to yield the corresponding type of catalog object. For example, if `type=ITEM`, the `CatalogObject` instance must have the ITEM-specific data set on the `item_data` attribute. The resulting `CatalogObject` instance is also a `CatalogItem` instance. In general, if `type=`, the `CatalogObject` instance must have the ``-specific data set on the `_data` attribute. The resulting `CatalogObject` instance is also a `Catalog` instance. For a more detailed discussion of the Catalog data model, please see the [Design a Catalog](https://developer.squareup.com/docs/catalog-api/design-a-catalog) guide.",
"properties": {
"type": {
"type": "string",
"description": "Possible types of CatalogObjects returned from the catalog, each containing type-specific properties in the `*_data` field corresponding to the specified object type.",
"enum": [
"ITEM",
"IMAGE",
"CATEGORY",
"ITEM_VARIATION",
"TAX",
"DISCOUNT",
"MODIFIER_LIST",
"MODIFIER",
"PRICING_RULE",
"PRODUCT_SET",
"TIME_PERIOD",
"MEASUREMENT_UNIT",
"SUBSCRIPTION_PLAN_VARIATION",
"ITEM_OPTION",
"ITEM_OPTION_VAL",
"CUSTOM_ATTRIBUTE_DEFINITION",
"QUICK_AMOUNTS_SETTINGS",
"SUBSCRIPTION_PLAN",
"AVAILABILITY_PERIOD"
]
},
"id": {
"type": "string",
"description": "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": {
"type": "string",
"description": "Last modification [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) 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": {
"type": "integer",
"description": "The version of the object. When updating an object, the version supplied must match the version in the database, otherwise the write will be rejected as conflicting."
},
"is_deleted": {
"type": "boolean",
"description": "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."
},
"custom_attribute_values": {
"type": "object",
"description": "A map (key-value pairs) of application-defined custom attribute values. The value of a key-value pair is a [CatalogCustomAttributeValue](entity:CatalogCustomAttributeValue) object. The key is the `key` attribute value defined in the associated [CatalogCustomAttributeDefinition](entity:CatalogCustomAttributeDefinition) object defined by the application making the request. If the `CatalogCustomAttributeDefinition` object is defined by another application, the `CatalogCustomAttributeDefinition`'s key attribute value is prefixed by the defining application ID. For example, if the `CatalogCustomAttributeDefinition` has a `key` attribute of `\"cocoa_brand\"` and the defining application ID is `\"abcd1234\"`, the key in the map is `\"abcd1234:cocoa_brand\"` if the application making the request is different from the application defining the custom attribute definition. Otherwise, the key used in the map is simply `\"cocoa_brand\"`. Application-defined custom attributes are set at a global (location-independent) level. Custom attribute values are intended to store additional information about a catalog object or associations with an entity in another system. Do not use custom attributes to store any sensitive information (personally identifiable information, card details, etc.)."
},
"catalog_v1_ids": {
"type": "array",
"items": {
"type": "object"
},
"description": "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": {
"type": "boolean",
"description": "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": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of locations where the object is present, even if `present_at_all_locations` is `false`. This can include locations that are deactivated."
},
"absent_at_location_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of locations where the object is not present, even if `present_at_all_locations` is `true`. This can include locations that are deactivated."
},
"item_data": {
"type": "object",
"description": "A [CatalogObject](entity:CatalogObject) instance of the `ITEM` type, also referred to as an item, in the catalog."
},
"category_data": {
"type": "object",
"description": "A category to which a `CatalogItem` instance belongs."
},
"item_variation_data": {
"type": "object",
"description": "An item variation, representing a product for sale, in the Catalog object model. Each [item](entity:CatalogItem) must have at least one item variation and can have at most 250 item variations. An item variation can be sellable, stockable, or both if it has a unit of measure for its count for the sold number of the variation, the stocked number of the variation, or both. For example, when a variation representing wine is stocked and sold by the bottle, the variation is both stockable and sellable. But when a variation of the wine is sold by the glass, the sold units cannot be used as a measure of the stocked units. This by-the-glass variation is sellable, but not stockable. To accurately keep track of the wine's inventory count at any time, the sellable count must be converted to stockable count. Typically, the seller defines this unit conversion. For example, 1 bottle equals 5 glasses. The Square API exposes the `stockable_conversion` property on the variation to specify the conversion. Thus, when two glasses of the wine are sold, the sellable count decreases by 2, and the stockable count automatically decreases by 0.4 bottle according to the conversion."
},
"tax_data": {
"type": "object",
"description": "A tax applicable to an item."
},
"discount_data": {
"type": "object",
"description": "A discount applicable to items."
},
"modifier_list_data": {
"type": "object",
"description": "A container for a list of modifiers, or a text-based modifier. For text-based modifiers, this represents text configuration for an item. (For example, custom text to print on a t-shirt). For non text-based modifiers, this represents a list of modifiers that can be applied to items at the time of sale. (For example, a list of condiments for a hot dog, or a list of ice cream flavors). Each element of the modifier list is a `CatalogObject` instance of the `MODIFIER` type."
},
"modifier_data": {
"type": "object",
"description": "A modifier that can be applied to items at the time of sale. For example, a cheese modifier for a burger, or a flavor modifier for a serving of ice cream."
},
"time_period_data": {
"type": "object",
"description": "Represents a time period - either a single period or a repeating period."
},
"product_set_data": {
"type": "object",
"description": "Represents a collection of catalog objects for the purpose of applying a `PricingRule`. Including a catalog object will include all of its subtypes. For example, including a category in a product set will include all of its items and associated item variations in the product set. Including an item in a product set will also include its item variations."
},
"pricing_rule_data": {
"type": "object",
"description": "Defines how discounts are automatically applied to a set of items that match the pricing rule during the active time period."
},
"image_data": {
"type": "object",
"description": "An image file to use in Square catalogs. It can be associated with `CatalogItem`, `CatalogItemVariation`, `CatalogCategory`, and `CatalogModifierList` objects. Only the images on items and item variations are exposed in Dashboard. Only the first image on an item is displayed in Square Point of Sale (SPOS). Images on items and variations are displayed through Square Online Store. Images on other object types are for use by 3rd party application developers."
},
"measurement_unit_data": {
"type": "object",
"description": "Represents the unit used to measure a `CatalogItemVariation` and specifies the precision for decimal quantities."
},
"subscription_plan_data": {
"type": "object",
"description": "Describes a subscription plan. A subscription plan represents what you want to sell in a subscription model, and includes references to each of the associated subscription plan variations. For more information, see [Subscription Plans and Variations](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations)."
},
"item_option_data": {
"type": "object",
"description": "A group of variations for a `CatalogItem`."
},
"item_option_value_data": {
"type": "object",
"description": "An enumerated value that can link a `CatalogItemVariation` to an item option as one of its item option values."
},
"custom_attribute_definition_data": {
"type": "object",
"description": "Contains information defining a custom attribute. Custom attributes are intended to store additional information about a catalog object or to associate a catalog object with an entity in another system. Do not use custom attributes to store any sensitive information (personally identifiable information, card details, etc.). [Read more about custom attributes](https://developer.squareup.com/docs/catalog-api/add-custom-attributes)"
},
"quick_amounts_settings_data": {
"type": "object",
"description": "A parent Catalog Object model represents a set of Quick Amounts and the settings control the amounts."
},
"subscription_plan_variation_data": {
"type": "object",
"description": "Describes a subscription plan variation. A subscription plan variation represents how the subscription for a product or service is sold. For more information, see [Subscription Plans and Variations](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations)."
},
"availability_period_data": {
"type": "object",
"description": "Represents a time period of availability."
}
},
"required": [
"type",
"id"
]
}
},
"required": [
"PCID",
"idempotency_key",
"object"
]
}
```
***
## square\_catalog\_upsert\_order\_custom\_attribute
UpsertOrderCustomAttribute
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ---------------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order_id` | string | Yes | — | The ID of the target order. | |
| `custom_attribute_key` | string | Yes | — | The key of the custom attribute to create or update. This key must match the key of an existing custom attribute definition. | |
| `custom_attribute` | object | Yes | — | A custom attribute value. Each custom attribute value has a corresponding `CustomAttributeDefinition` object. | |
| `idempotency_key` | string | null | No | — | A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"order_id": {
"type": "string",
"description": "The ID of the target [order](entity:Order)."
},
"custom_attribute_key": {
"type": "string",
"description": "The key of the custom attribute to create or update. This key must match the key of an existing custom attribute definition."
},
"custom_attribute": {
"type": "object",
"description": "A custom attribute value. Each custom attribute value has a corresponding `CustomAttributeDefinition` object.",
"properties": {
"key": {
"type": "string",
"description": "The identifier of the custom attribute definition and its corresponding custom attributes. This value can be a simple key, which is the key that is provided when the custom attribute definition is created, or a qualified key, if the requesting application is not the definition owner. The qualified key consists of the application ID of the custom attribute definition owner followed by the simple key that was provided when the definition was created. It has the format application_id:simple key. The value for a simple key can contain up to 60 alphanumeric characters, periods (.), underscores (_), and hyphens (-)."
},
"value": {
"description": "The value assigned to the custom attribute. It is validated against the custom attribute definition's schema on write operations. For more information about custom attribute values, see [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview)."
},
"version": {
"type": "integer",
"description": "Read only. The current version of the custom attribute. This field is incremented when the custom attribute is changed. When updating an existing custom attribute value, you can provide this field and specify the current version of the custom attribute to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency). This field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads, see [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview)."
},
"visibility": {
"type": "string",
"description": "The level of permission that a seller or other applications requires to view this custom attribute definition. The `Visibility` field controls who can read and write the custom attribute values and custom attribute definition.",
"enum": [
"VISIBILITY_HIDDEN",
"VISIBILITY_READ_ONLY",
"VISIBILITY_READ_WRITE_VALUES"
]
},
"definition": {
"type": "object",
"description": "Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute."
},
"updated_at": {
"type": "string",
"description": "The timestamp that indicates when the custom attribute was created or was most recently updated, in RFC 3339 format."
},
"created_at": {
"type": "string",
"description": "The timestamp that indicates when the custom attribute was created, in RFC 3339 format."
}
}
},
"idempotency_key": {
"type": [
"string",
"null"
],
"description": "A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
}
},
"required": [
"PCID",
"order_id",
"custom_attribute_key",
"custom_attribute"
]
}
```