{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/square/main/json-schema/square-search-catalog-objects-response-schema.json", "title": "SearchCatalogObjectsResponse", "x-generated": "2026-10-12", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/square-catalog-api-openapi.yml#/components/schemas/SearchCatalogObjectsResponse", "type": "object", "x-release-status": "PUBLIC", "properties": { "errors": { "type": "array", "items": { "$ref": "#/$defs/Error" }, "description": "Any errors that occurred during the request." }, "cursor": { "type": "string", "description": "The pagination cursor to be used in a subsequent request. If unset, this is the final response.\nSee [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information." }, "objects": { "type": "array", "items": { "$ref": "#/$defs/CatalogObject" }, "description": "The CatalogObjects returned." }, "related_objects": { "type": "array", "items": { "$ref": "#/$defs/CatalogObject" }, "description": "A list of CatalogObjects referenced by the objects in the `objects` field." }, "latest_time": { "type": "string", "description": "When the associated product catalog was last updated. Will\nmatch the value for `end_time` or `cursor` if either field is included in the `SearchCatalog` request.", "x-release-status": "BETA" } }, "x-sq-sdk-sample-code": { "csharp": "/sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsResponse.csharp", "java": "/sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsResponse.java", "javascript": "/sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsResponse.javascript", "php": "/sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsResponse.php", "python": "/sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsResponse.python", "ruby": "/sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsResponse.ruby" }, "$defs": { "CatalogAvailabilityPeriod": { "type": "object", "description": "Represents a time period of availability.", "x-release-status": "BETA", "properties": { "start_local_time": { "type": [ "string", "null" ], "description": "The start time of an availability period, specified in local time using partial-time\nRFC 3339 format. For example, `8:30:00` for a period starting at 8:30 in the morning.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC." }, "end_local_time": { "type": [ "string", "null" ], "description": "The end time of an availability period, specified in local time using partial-time\nRFC 3339 format. For example, `21:00:00` for a period ending at 9:00 in the evening.\nNote that the seconds value is always :00, but it is appended for conformance to the RFC." }, "day_of_week": { "$ref": "#/$defs/DayOfWeek", "description": "The day of the week for this availability period.\nSee [DayOfWeek](#type-dayofweek) for possible values" } } }, "CatalogCategory": { "type": "object", "description": "A category to which a `CatalogItem` instance belongs.", "x-release-status": "PUBLIC", "properties": { "name": { "type": [ "string", "null" ], "description": "The category name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "maxLength": 255 }, "image_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The IDs of images associated with this `CatalogCategory` instance.\nCurrently these images are not displayed by Square, but are free to be displayed in 3rd party applications." }, "category_type": { "$ref": "#/$defs/CatalogCategoryType", "description": "The type of the category.\nSee [CatalogCategoryType](#type-catalogcategorytype) for possible values" }, "parent_category": { "$ref": "#/$defs/CatalogObjectCategory", "description": "The ID of the parent category of this category instance." }, "is_top_level": { "type": [ "boolean", "null" ], "description": "Indicates whether a category is a top level category, which does not have any parent_category." }, "channels": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "A list of IDs representing channels, such as a Square Online site, where the category can be made visible." }, "availability_period_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The IDs of the `CatalogAvailabilityPeriod` objects associated with the category." }, "online_visibility": { "type": [ "boolean", "null" ], "description": "Indicates whether the category is visible (`true`) or hidden (`false`) on all of the seller's Square Online sites." }, "root_category": { "type": "string", "description": "The top-level category in a category hierarchy.", "readOnly": true }, "ecom_seo_data": { "$ref": "#/$defs/CatalogEcomSeoData", "description": "The SEO data for a seller's Square Online store." }, "path_to_root": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CategoryPathToRootNode" }, "description": "The path from the category to its root category. The first node of the path is the parent of the category\nand the last is the root category. The path is empty if the category is a root category." } } }, "CatalogCategoryType": { "type": "string", "enum": [ "REGULAR_CATEGORY", "MENU_CATEGORY", "KITCHEN_CATEGORY" ], "x-enum-elements": [ { "name": "REGULAR_CATEGORY", "description": "The regular category." }, { "name": "MENU_CATEGORY", "description": "The menu category." }, { "name": "KITCHEN_CATEGORY", "description": "Kitchen categories are used by KDS (Kitchen Display System) to route items to specific clients" } ], "description": "Indicates the type of a category.", "x-release-status": "PUBLIC" }, "CatalogCustomAttributeDefinition": { "type": "object", "description": "Contains information defining a custom attribute. Custom attributes are\nintended to store additional information about a catalog object or to associate a\ncatalog object with an entity in another system. Do not use custom attributes\nto store any sensitive information (personally identifiable information, card details, etc.).\n[Read more about custom attributes](https://developer.squareup.com/docs/catalog-api/add-custom-attributes)", "x-release-status": "PUBLIC", "required": [ "type", "name", "allowed_object_types" ], "properties": { "type": { "$ref": "#/$defs/CatalogCustomAttributeDefinitionType", "description": "The type of this custom attribute. Cannot be modified after creation.\nRequired.\nSee [CatalogCustomAttributeDefinitionType](#type-catalogcustomattributedefinitiontype) for possible values" }, "name": { "type": "string", "description": " The name of this definition for API and seller-facing UI purposes.\nThe name must be unique within the (merchant, application) pair. Required.\nMay not be empty and may not exceed 255 characters. Can be modified after creation.", "minLength": 1, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Seller-oriented description of the meaning of this Custom Attribute,\nany constraints that the seller should observe, etc. May be displayed as a tooltip in Square UIs.", "maxLength": 255 }, "source_application": { "$ref": "#/$defs/SourceApplication", "description": "__Read only.__ Contains information about the application that\ncreated this custom attribute definition." }, "allowed_object_types": { "type": "array", "items": { "$ref": "#/$defs/CatalogObjectType" }, "description": "The set of `CatalogObject` types that this custom atttribute may be applied to.\nCurrently, only `ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, and `CATEGORY` are allowed. At least one type must be included.\nSee [CatalogObjectType](#type-catalogobjecttype) for possible values" }, "seller_visibility": { "$ref": "#/$defs/CatalogCustomAttributeDefinitionSellerVisibility", "description": "The visibility of a custom attribute in seller-facing UIs (including Square Point\nof Sale applications and Square Dashboard). May be modified.\nSee [CatalogCustomAttributeDefinitionSellerVisibility](#type-catalogcustomattributedefinitionsellervisibility) for possible values" }, "app_visibility": { "$ref": "#/$defs/CatalogCustomAttributeDefinitionAppVisibility", "description": "The visibility of a custom attribute to applications other than the application\nthat created the attribute.\nSee [CatalogCustomAttributeDefinitionAppVisibility](#type-catalogcustomattributedefinitionappvisibility) for possible values" }, "string_config": { "$ref": "#/$defs/CatalogCustomAttributeDefinitionStringConfig", "description": "Optionally, populated when `type` = `STRING`, unset otherwise." }, "number_config": { "$ref": "#/$defs/CatalogCustomAttributeDefinitionNumberConfig", "description": "Optionally, populated when `type` = `NUMBER`, unset otherwise." }, "selection_config": { "$ref": "#/$defs/CatalogCustomAttributeDefinitionSelectionConfig", "description": "Populated when `type` is set to `SELECTION`, unset otherwise." }, "custom_attribute_usage_count": { "type": "integer", "description": "The number of custom attributes that reference this\ncustom attribute definition. Set by the server in response to a ListCatalog\nrequest with `include_counts` set to `true`. If the actual count is greater\nthan 100, `custom_attribute_usage_count` will be set to `100`.", "readOnly": true }, "key": { "type": [ "string", "null" ], "description": "The name of the desired custom attribute key that can be used to access\nthe custom attribute value on catalog objects. Cannot be modified after the\ncustom attribute definition has been created.\nMust be between 1 and 60 characters, and may only contain the characters `[a-zA-Z0-9_-]`.", "minLength": 1, "maxLength": 60, "pattern": "^[a-zA-Z0-9_-]*$" } } }, "CatalogCustomAttributeDefinitionAppVisibility": { "type": "string", "enum": [ "APP_VISIBILITY_HIDDEN", "APP_VISIBILITY_READ_ONLY", "APP_VISIBILITY_READ_WRITE_VALUES" ], "x-enum-elements": [ { "name": "APP_VISIBILITY_HIDDEN", "description": "Other applications cannot read this custom attribute." }, { "name": "APP_VISIBILITY_READ_ONLY", "description": "Other applications can read this custom attribute definition and\nvalues." }, { "name": "APP_VISIBILITY_READ_WRITE_VALUES", "description": "Other applications can read and write custom attribute values on objects.\nThey can read but cannot edit the custom attribute definition." } ], "description": "Defines the visibility of a custom attribute to applications other than their\ncreating application.", "x-release-status": "PUBLIC" }, "CatalogCustomAttributeDefinitionNumberConfig": { "type": "object", "x-release-status": "PUBLIC", "properties": { "precision": { "type": [ "integer", "null" ], "description": "An integer between 0 and 5 that represents the maximum number of\npositions allowed after the decimal in number custom attribute values\nFor example:\n\n- if the precision is 0, the quantity can be 1, 2, 3, etc.\n- if the precision is 1, the quantity can be 0.1, 0.2, etc.\n- if the precision is 2, the quantity can be 0.01, 0.12, etc.\n\nDefault: 5", "maximum": 5 } } }, "CatalogCustomAttributeDefinitionSelectionConfig": { "type": "object", "description": "Configuration associated with `SELECTION`-type custom attribute definitions.", "x-release-status": "PUBLIC", "properties": { "max_allowed_selections": { "type": [ "integer", "null" ], "description": "The maximum number of selections that can be set. The maximum value for this\nattribute is 100. The default value is 1. The value can be modified, but changing the value will not\naffect existing custom attribute values on objects. Clients need to\nhandle custom attributes with more selected values than allowed by this limit.", "maximum": 100 }, "allowed_selections": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection" }, "description": "The set of valid `CatalogCustomAttributeSelections`. Up to a maximum of 100\nselections can be defined. Can be modified." } } }, "CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection": { "type": "object", "description": "A named selection for this `SELECTION`-type custom attribute definition.", "x-release-status": "PUBLIC", "required": [ "name" ], "properties": { "uid": { "type": [ "string", "null" ], "description": "Unique ID set by Square." }, "name": { "type": "string", "description": "Selection name, unique within `allowed_selections`.", "minLength": 1, "maxLength": 255 } } }, "CatalogCustomAttributeDefinitionSellerVisibility": { "type": "string", "enum": [ "SELLER_VISIBILITY_HIDDEN", "SELLER_VISIBILITY_READ_WRITE_VALUES" ], "x-enum-elements": [ { "name": "SELLER_VISIBILITY_HIDDEN", "description": "Sellers cannot read this custom attribute in Square client\napplications or Square APIs." }, { "name": "SELLER_VISIBILITY_READ_WRITE_VALUES", "description": "Sellers can read and write this custom attribute value in catalog objects,\nbut cannot edit the custom attribute definition." } ], "description": "Defines the visibility of a custom attribute to sellers in Square\nclient applications, Square APIs or in Square UIs (including Square Point\nof Sale applications and Square Dashboard).", "x-release-status": "PUBLIC" }, "CatalogCustomAttributeDefinitionStringConfig": { "type": "object", "description": "Configuration associated with Custom Attribute Definitions of type `STRING`.", "x-release-status": "PUBLIC", "properties": { "enforce_uniqueness": { "type": [ "boolean", "null" ], "description": "If true, each Custom Attribute instance associated with this Custom Attribute\nDefinition must have a unique value within the seller's catalog. For\nexample, this may be used for a value like a SKU that should not be\nduplicated within a seller's catalog. May not be modified after the\ndefinition has been created." } } }, "CatalogCustomAttributeDefinitionType": { "type": "string", "enum": [ "STRING", "BOOLEAN", "NUMBER", "SELECTION" ], "x-enum-elements": [ { "name": "STRING", "description": "A free-form string containing up to 255 characters." }, { "name": "BOOLEAN", "description": "A `true` or `false` value." }, { "name": "NUMBER", "description": "A decimal string representation of a number. Can support up to 5 digits after the decimal point." }, { "name": "SELECTION", "description": "One or more choices from `allowed_selections`." } ], "description": "Defines the possible types for a custom attribute.", "x-release-status": "PUBLIC" }, "CatalogCustomAttributeValue": { "type": "object", "description": "An instance of a custom attribute. Custom attributes can be defined and\nadded to `ITEM` and `ITEM_VARIATION` type catalog objects.\n[Read more about custom attributes](https://developer.squareup.com/docs/catalog-api/add-custom-attributes).", "x-release-status": "PUBLIC", "properties": { "name": { "type": [ "string", "null" ], "description": "The name of the custom attribute." }, "string_value": { "type": [ "string", "null" ], "description": "The string value of the custom attribute. Populated if `type` = `STRING`." }, "custom_attribute_definition_id": { "type": "string", "description": "The id of the [CatalogCustomAttributeDefinition](entity:CatalogCustomAttributeDefinition) this value belongs to.", "readOnly": true }, "type": { "$ref": "#/$defs/CatalogCustomAttributeDefinitionType", "description": "A copy of type from the associated `CatalogCustomAttributeDefinition`.\nSee [CatalogCustomAttributeDefinitionType](#type-catalogcustomattributedefinitiontype) for possible values", "readOnly": true }, "number_value": { "type": [ "string", "null" ], "description": "Populated if `type` = `NUMBER`. Contains a string\nrepresentation of a decimal number, using a `.` as the decimal separator." }, "boolean_value": { "type": [ "boolean", "null" ], "description": "A `true` or `false` value. Populated if `type` = `BOOLEAN`." }, "selection_uid_values": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "One or more choices from `allowed_selections`. Populated if `type` = `SELECTION`." }, "key": { "type": "string", "description": "If the associated `CatalogCustomAttributeDefinition` object is defined by another application, this key is prefixed by the defining application ID.\nFor example, if the CatalogCustomAttributeDefinition has a key attribute of \"cocoa_brand\" and the defining application ID is \"abcd1234\", this key is \"abcd1234:cocoa_brand\"\nwhen the application making the request is different from the application defining the custom attribute definition. Otherwise, the key is simply \"cocoa_brand\".", "readOnly": true } } }, "CatalogDiscount": { "type": "object", "description": "A discount applicable to items.", "x-release-status": "PUBLIC", "properties": { "name": { "type": [ "string", "null" ], "description": "The discount name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "maxLength": 255 }, "discount_type": { "$ref": "#/$defs/CatalogDiscountType", "description": "Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale.\nSee [CatalogDiscountType](#type-catalogdiscounttype) for possible values" }, "percentage": { "type": [ "string", "null" ], "description": "The percentage of the discount as a string representation of a decimal number, using a `.` as the decimal\nseparator and without a `%` sign. A value of `7.5` corresponds to `7.5%`. Specify a percentage of `0` if `discount_type`\nis `VARIABLE_PERCENTAGE`.\n\nDo not use this field for amount-based or variable discounts." }, "amount_money": { "$ref": "#/$defs/Money", "description": "The amount of the discount. Specify an amount of `0` if `discount_type` is `VARIABLE_AMOUNT`.\n\nDo not use this field for percentage-based or variable discounts." }, "pin_required": { "type": [ "boolean", "null" ], "description": "Indicates whether a mobile staff member needs to enter their PIN to apply the\ndiscount to a payment in the Square Point of Sale app." }, "label_color": { "type": [ "string", "null" ], "description": "The color of the discount display label in the Square Point of Sale app. This must be a valid hex color code." }, "modify_tax_basis": { "$ref": "#/$defs/CatalogDiscountModifyTaxBasis", "description": "Indicates whether this discount should reduce the price used to calculate tax.\n\nMost discounts should use `MODIFY_TAX_BASIS`. However, in some circumstances taxes must\nbe calculated based on an item's price, ignoring a particular discount. For example,\nin many US jurisdictions, a manufacturer coupon or instant rebate reduces the price a\ncustomer pays but does not reduce the sale price used to calculate how much sales tax is\ndue. In this case, the discount representing that manufacturer coupon should have\n`DO_NOT_MODIFY_TAX_BASIS` for this field.\n\nIf you are unsure whether you need to use this field, consult your tax professional.\nSee [CatalogDiscountModifyTaxBasis](#type-catalogdiscountmodifytaxbasis) for possible values" }, "maximum_amount_money": { "$ref": "#/$defs/Money", "description": "For a percentage discount, the maximum absolute value of the discount. For example, if a\n50% discount has a `maximum_amount_money` of $20, a $100 purchase will yield a $20 discount,\nnot a $50 discount." } } }, "CatalogDiscountModifyTaxBasis": { "type": "string", "enum": [ "MODIFY_TAX_BASIS", "DO_NOT_MODIFY_TAX_BASIS" ], "x-enum-elements": [ { "name": "MODIFY_TAX_BASIS", "description": "Application of the discount will modify the tax basis." }, { "name": "DO_NOT_MODIFY_TAX_BASIS", "description": "Application of the discount will not modify the tax basis." } ], "x-release-status": "PUBLIC" }, "CatalogDiscountType": { "type": "string", "enum": [ "FIXED_PERCENTAGE", "FIXED_AMOUNT", "VARIABLE_PERCENTAGE", "VARIABLE_AMOUNT" ], "x-enum-elements": [ { "name": "FIXED_PERCENTAGE", "description": "Apply the discount as a fixed percentage (e.g., 5%) off the item price." }, { "name": "FIXED_AMOUNT", "description": "Apply the discount as a fixed amount (e.g., $1.00) off the item price." }, { "name": "VARIABLE_PERCENTAGE", "description": "Apply the discount as a variable percentage off the item price. The percentage will be specified at the time of sale." }, { "name": "VARIABLE_AMOUNT", "description": "Apply the discount as a variable amount off the item price. The amount will be specified at the time of sale." } ], "description": "How to apply a CatalogDiscount to a CatalogItem.", "x-release-status": "PUBLIC" }, "CatalogEcomSeoData": { "type": "object", "description": "SEO data for for a seller's Square Online store.", "x-release-status": "PUBLIC", "properties": { "page_title": { "type": [ "string", "null" ], "description": "The SEO title used for the Square Online store." }, "page_description": { "type": [ "string", "null" ], "description": "The SEO description used for the Square Online store." }, "permalink": { "type": [ "string", "null" ], "description": "The SEO permalink used for the Square Online store." } } }, "CatalogImage": { "type": "object", "description": "An image file to use in Square catalogs. It can be associated with\n`CatalogItem`, `CatalogItemVariation`, `CatalogCategory`, and `CatalogModifierList` objects.\nOnly the images on items and item variations are exposed in Dashboard.\nOnly the first image on an item is displayed in Square Point of Sale (SPOS).\nImages on items and variations are displayed through Square Online Store.\nImages on other object types are for use by 3rd party application developers.", "x-release-status": "PUBLIC", "properties": { "name": { "type": [ "string", "null" ], "description": "The internal name to identify this image in calls to the Square API.\nThis is a searchable attribute for use in applicable query filters\nusing the [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects).\nIt is not unique and should not be shown in a buyer facing context." }, "url": { "type": [ "string", "null" ], "description": "The URL of this image, generated by Square after an image is uploaded\nusing the [CreateCatalogImage](api-endpoint:Catalog-CreateCatalogImage) endpoint.\nTo modify the image, use the UpdateCatalogImage endpoint. Do not change the URL field." }, "caption": { "type": [ "string", "null" ], "description": "A caption that describes what is shown in the image. Displayed in the\nSquare Online Store. This is a searchable attribute for use in applicable query filters\nusing the [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects)." }, "photo_studio_order_id": { "type": [ "string", "null" ], "description": "The immutable order ID for this image object created by the Photo Studio service in Square Online Store." } } }, "CatalogItem": { "type": "object", "description": "A [CatalogObject](entity:CatalogObject) instance of the `ITEM` type, also referred to as an item, in the catalog.", "x-release-status": "PUBLIC", "properties": { "name": { "type": [ "string", "null" ], "description": "The item's name. This is a searchable attribute for use in applicable query filters, its value must not be empty, and the length is of Unicode code points.", "maxLength": 512 }, "description": { "type": [ "string", "null" ], "description": "The item's description. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.\n\nDeprecated at 2022-07-20, this field is planned to retire in 6 months. You should migrate to use `description_html` to set the description\nof the [CatalogItem](entity:CatalogItem) instance. The `description` and `description_html` field values are kept in sync. If you try to\nset the both fields, the `description_html` text value overwrites the `description` value. Updates in one field are also reflected in the other,\nexcept for when you use an early version before Square API 2022-07-20 and `description_html` is set to blank, setting the `description` value to null\ndoes not nullify `description_html`.", "maxLength": 4096, "x-release-status": "DEPRECATED" }, "abbreviation": { "type": [ "string", "null" ], "description": "The text of the item's display label in the Square Point of Sale app. Only up to the first five characters of the string are used.\nThis attribute is searchable, and its value length is of Unicode code points.", "maxLength": 24 }, "label_color": { "type": [ "string", "null" ], "description": "The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code." }, "is_taxable": { "type": [ "boolean", "null" ], "description": "Indicates whether the item is taxable (`true`) or non-taxable (`false`). Default is `true`." }, "category_id": { "type": [ "string", "null" ], "description": "The ID of the item's category, if any. Deprecated since 2023-12-13. Use `CatalogItem.categories`, instead.", "x-release-status": "DEPRECATED" }, "tax_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "A set of IDs indicating the taxes enabled for\nthis item. When updating an item, any taxes listed here will be added to the item.\nTaxes may also be added to or deleted from an item using `UpdateItemTaxes`." }, "modifier_list_info": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CatalogItemModifierListInfo" }, "description": "A set of `CatalogItemModifierListInfo` objects\nrepresenting the modifier lists that apply to this item, along with the overrides and min\nand max limits that are specific to this item. Modifier lists\nmay also be added to or deleted from an item using `UpdateItemModifierLists`." }, "variations": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CatalogObject" }, "description": "A list of [CatalogItemVariation](entity:CatalogItemVariation) objects for this item. An item must have\nat least one variation." }, "product_type": { "$ref": "#/$defs/CatalogItemProductType", "description": "The product type of the item. Once set, the `product_type` value cannot be modified.\n\nItems of the `LEGACY_SQUARE_ONLINE_SERVICE` and `LEGACY_SQUARE_ONLINE_MEMBERSHIP` product types can be updated\nbut cannot be created using the API.\nSee [CatalogItemProductType](#type-catalogitemproducttype) for possible values" }, "skip_modifier_screen": { "type": [ "boolean", "null" ], "description": "If `false`, the Square Point of Sale app will present the `CatalogItem`'s\ndetails screen immediately, allowing the merchant to choose `CatalogModifier`s\nbefore adding the item to the cart. This is the default behavior.\n\nIf `true`, the Square Point of Sale app will immediately add the item to the cart with the pre-selected\nmodifiers, and merchants can edit modifiers by drilling down onto the item's details.\n\nThird-party clients are encouraged to implement similar behaviors." }, "item_options": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CatalogItemOptionForItem" }, "description": "List of item options IDs for this item. Used to manage and group item\nvariations in a specified order.\n\nMaximum: 6 item options." }, "image_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The IDs of images associated with this `CatalogItem` instance.\nThese images will be shown to customers in Square Online Store.\nThe first image will show up as the icon for this item in POS.", "x-release-status": "BETA" }, "sort_name": { "type": [ "string", "null" ], "description": "A name to sort the item by. If this name is unspecified, namely, the `sort_name` field is absent, the regular `name` field is used for sorting.\nIts value must not be empty.\n\nIt is currently supported for sellers of the Japanese locale only.", "x-release-status": "BETA" }, "categories": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CatalogObjectCategory" }, "description": "The list of categories." }, "description_html": { "type": [ "string", "null" ], "description": "The item's description as expressed in valid HTML elements. The length of this field value, including those of HTML tags,\nis of Unicode points. With application query filters, the text values of the HTML elements and attributes are searchable. Invalid or\nunsupported HTML elements or attributes are ignored.\n\nSupported HTML elements include:\n- `a`: Link. Supports linking to website URLs, email address, and telephone numbers.\n- `b`, `strong`: Bold text\n- `br`: Line break\n- `code`: Computer code\n- `div`: Section\n- `h1-h6`: Headings\n- `i`, `em`: Italics\n- `li`: List element\n- `ol`: Numbered list\n- `p`: Paragraph\n- `ul`: Bullet list\n- `u`: Underline\n\n\nSupported HTML attributes include:\n- `align`: Alignment of the text content\n- `href`: Link destination\n- `rel`: Relationship between link's target and source\n- `target`: Place to open the linked document", "maxLength": 65535 }, "description_plaintext": { "type": "string", "description": "A server-generated plaintext version of the `description_html` field, without formatting tags.", "maxLength": 65535, "readOnly": true }, "channels": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "A list of IDs representing channels, such as a Square Online site, where the item can be made visible or available.\nThis field is read only and cannot be edited." }, "is_archived": { "type": [ "boolean", "null" ], "description": "Indicates whether this item is archived (`true`) or not (`false`)." }, "ecom_seo_data": { "$ref": "#/$defs/CatalogEcomSeoData", "description": "The SEO data for a seller's Square Online store." }, "food_and_beverage_details": { "$ref": "#/$defs/CatalogItemFoodAndBeverageDetails", "description": "The food and beverage-specific details for the `FOOD_AND_BEV` item." }, "reporting_category": { "$ref": "#/$defs/CatalogObjectCategory", "description": "The item's reporting category." } } }, "CatalogItemFoodAndBeverageDetails": { "type": "object", "description": "The food and beverage-specific details of a `FOOD_AND_BEV` item.", "x-release-status": "PUBLIC", "properties": { "calorie_count": { "type": [ "integer", "null" ], "description": "The calorie count (in the unit of kcal) for the `FOOD_AND_BEV` type of items." }, "dietary_preferences": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CatalogItemFoodAndBeverageDetailsDietaryPreference" }, "description": "The dietary preferences for the `FOOD_AND_BEV` item." }, "ingredients": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CatalogItemFoodAndBeverageDetailsIngredient" }, "description": "The ingredients for the `FOOD_AND_BEV` type item." } } }, "CatalogItemFoodAndBeverageDetailsDietaryPreference": { "type": "object", "description": "Dietary preferences that can be assigned to an `FOOD_AND_BEV` item and its ingredients.", "x-release-status": "PUBLIC", "properties": { "type": { "$ref": "#/$defs/CatalogItemFoodAndBeverageDetailsDietaryPreferenceType", "description": "The dietary preference type. Supported values include `STANDARD` and `CUSTOM` as specified in `FoodAndBeverageDetails.DietaryPreferenceType`.\nSee [DietaryPreferenceType](#type-dietarypreferencetype) for possible values" }, "standard_name": { "$ref": "#/$defs/CatalogItemFoodAndBeverageDetailsDietaryPreferenceStandardDietaryPreference", "description": "The name of the dietary preference from a standard pre-defined list. This should be null if it's a custom dietary preference.\nSee [StandardDietaryPreference](#type-standarddietarypreference) for possible values" }, "custom_name": { "type": [ "string", "null" ], "description": "The name of a user-defined custom dietary preference. This should be null if it's a standard dietary preference." } } }, "CatalogItemFoodAndBeverageDetailsDietaryPreferenceStandardDietaryPreference": { "type": "string", "enum": [ "DAIRY_FREE", "GLUTEN_FREE", "HALAL", "KOSHER", "NUT_FREE", "VEGAN", "VEGETARIAN" ], "x-enum-elements": [ { "name": "DAIRY_FREE", "description": "" }, { "name": "GLUTEN_FREE", "description": "" }, { "name": "HALAL", "description": "" }, { "name": "KOSHER", "description": "" }, { "name": "NUT_FREE", "description": "" }, { "name": "VEGAN", "description": "" }, { "name": "VEGETARIAN", "description": "" } ], "description": "Standard dietary preferences for food and beverage items that are recommended on item creation.", "x-release-status": "PUBLIC" }, "CatalogItemFoodAndBeverageDetailsDietaryPreferenceType": { "type": "string", "enum": [ "STANDARD", "CUSTOM" ], "x-enum-elements": [ { "name": "STANDARD", "description": "A standard value from a pre-determined list." }, { "name": "CUSTOM", "description": "A user-defined custom value." } ], "description": "The type of dietary preference for the `FOOD_AND_BEV` type of items and integredients.", "x-release-status": "PUBLIC" }, "CatalogItemFoodAndBeverageDetailsIngredient": { "type": "object", "description": "Describes the ingredient used in a `FOOD_AND_BEV` item.", "x-release-status": "PUBLIC", "properties": { "type": { "$ref": "#/$defs/CatalogItemFoodAndBeverageDetailsDietaryPreferenceType", "description": "The dietary preference type of the ingredient. Supported values include `STANDARD` and `CUSTOM` as specified in `FoodAndBeverageDetails.DietaryPreferenceType`.\nSee [DietaryPreferenceType](#type-dietarypreferencetype) for possible values" }, "standard_name": { "$ref": "#/$defs/CatalogItemFoodAndBeverageDetailsIngredientStandardIngredient", "description": "The name of the ingredient from a standard pre-defined list. This should be null if it's a custom dietary preference.\nSee [StandardIngredient](#type-standardingredient) for possible values" }, "custom_name": { "type": [ "string", "null" ], "description": "The name of a custom user-defined ingredient. This should be null if it's a standard dietary preference." } } }, "CatalogItemFoodAndBeverageDetailsIngredientStandardIngredient": { "type": "string", "enum": [ "CELERY", "CRUSTACEANS", "EGGS", "FISH", "GLUTEN", "LUPIN", "MILK", "MOLLUSCS", "MUSTARD", "PEANUTS", "SESAME", "SOY", "SULPHITES", "TREE_NUTS" ], "x-enum-elements": [ { "name": "CELERY", "description": "" }, { "name": "CRUSTACEANS", "description": "" }, { "name": "EGGS", "description": "" }, { "name": "FISH", "description": "" }, { "name": "GLUTEN", "description": "" }, { "name": "LUPIN", "description": "" }, { "name": "MILK", "description": "" }, { "name": "MOLLUSCS", "description": "" }, { "name": "MUSTARD", "description": "" }, { "name": "PEANUTS", "description": "" }, { "name": "SESAME", "description": "" }, { "name": "SOY", "description": "" }, { "name": "SULPHITES", "description": "" }, { "name": "TREE_NUTS", "description": "" } ], "description": "Standard ingredients for food and beverage items that are recommended on item creation.", "x-release-status": "PUBLIC" }, "CatalogItemModifierListInfo": { "type": "object", "description": "References a text-based modifier or a list of non text-based modifiers applied to a `CatalogItem` instance\nand specifies supported behaviors of the application.", "x-release-status": "PUBLIC", "required": [ "modifier_list_id" ], "properties": { "modifier_list_id": { "type": "string", "description": "The ID of the `CatalogModifierList` controlled by this `CatalogModifierListInfo`.", "minLength": 1 }, "modifier_overrides": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CatalogModifierOverride" }, "description": "A set of `CatalogModifierOverride` objects that override whether a given `CatalogModifier` is enabled by default." }, "min_selected_modifiers": { "type": [ "integer", "null" ], "description": "If 0 or larger, the smallest number of `CatalogModifier`s that must be selected from this `CatalogModifierList`.\nThe default value is `-1`.\n\nWhen `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` \nand `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of\nthe `CatalogModifierList` can be selected from the `CatalogModifierList`. \n\nWhen the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1`\nand `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in \nand can be selected from the `CatalogModifierList`" }, "max_selected_modifiers": { "type": [ "integer", "null" ], "description": "If 0 or larger, the largest number of `CatalogModifier`s that can be selected from this `CatalogModifierList`.\nThe default value is `-1`.\n\nWhen `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` \nand `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of\nthe `CatalogModifierList` can be selected from the `CatalogModifierList`. \n\nWhen the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1`\nand `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in \nand can be selected from the `CatalogModifierList`" }, "enabled": { "type": [ "boolean", "null" ], "description": "If `true`, enable this `CatalogModifierList`. The default value is `true`." }, "ordinal": { "type": [ "integer", "null" ], "description": "The position of this `CatalogItemModifierListInfo` object within the `modifier_list_info` list applied \nto a `CatalogItem` instance.", "x-release-status": "BETA" } } }, "CatalogItemOption": { "type": "object", "description": "A group of variations for a `CatalogItem`.", "x-release-status": "PUBLIC", "properties": { "name": { "type": [ "string", "null" ], "description": "The item option's display name for the seller. Must be unique across\nall item options. This is a searchable attribute for use in applicable query filters." }, "display_name": { "type": [ "string", "null" ], "description": "The item option's display name for the customer. This is a searchable attribute for use in applicable query filters." }, "description": { "type": [ "string", "null" ], "description": "The item option's human-readable description. Displayed in the Square\nPoint of Sale app for the seller and in the Online Store or on receipts for\nthe buyer. This is a searchable attribute for use in applicable query filters." }, "show_colors": { "type": [ "boolean", "null" ], "description": "If true, display colors for entries in `values` when present." }, "values": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CatalogObject" }, "description": "A list of CatalogObjects containing the\n`CatalogItemOptionValue`s for this item." } } }, "CatalogItemOptionForItem": { "type": "object", "description": " An option that can be assigned to an item.\nFor example, a t-shirt item may offer a color option or a size option.", "x-release-status": "BETA", "properties": { "item_option_id": { "type": [ "string", "null" ], "description": "The unique id of the item option, used to form the dimensions of the item option matrix in a specified order." } } }, "CatalogItemOptionValue": { "type": "object", "description": "An enumerated value that can link a\n`CatalogItemVariation` to an item option as one of\nits item option values.", "x-release-status": "PUBLIC", "properties": { "item_option_id": { "type": [ "string", "null" ], "description": "Unique ID of the associated item option." }, "name": { "type": [ "string", "null" ], "description": "Name of this item option value. This is a searchable attribute for use in applicable query filters." }, "description": { "type": [ "string", "null" ], "description": "A human-readable description for the option value. This is a searchable attribute for use in applicable query filters." }, "color": { "type": [ "string", "null" ], "description": "The HTML-supported hex color for the item option (e.g., \"#ff8d4e85\").\nOnly displayed if `show_colors` is enabled on the parent `ItemOption`. When\nleft unset, `color` defaults to white (\"#ffffff\") when `show_colors` is\nenabled on the parent `ItemOption`." }, "ordinal": { "type": [ "integer", "null" ], "description": "Determines where this option value appears in a list of option values." } } }, "CatalogItemOptionValueForItemVariation": { "type": "object", "description": "A `CatalogItemOptionValue` links an item variation to an item option as\nan item option value. For example, a t-shirt item may offer a color option and\na size option. An item option value would represent each variation of t-shirt:\nFor example, \"Color:Red, Size:Small\" or \"Color:Blue, Size:Medium\".", "x-release-status": "PUBLIC", "properties": { "item_option_id": { "type": [ "string", "null" ], "description": "The unique id of an item option." }, "item_option_value_id": { "type": [ "string", "null" ], "description": "The unique id of the selected value for the item option." } } }, "CatalogItemProductType": { "type": "string", "enum": [ "REGULAR", "GIFT_CARD", "APPOINTMENTS_SERVICE", "FOOD_AND_BEV", "EVENT", "DIGITAL", "DONATION", "LEGACY_SQUARE_ONLINE_SERVICE", "LEGACY_SQUARE_ONLINE_MEMBERSHIP" ], "x-enum-elements": [ { "name": "REGULAR", "description": "An ordinary item." }, { "name": "GIFT_CARD", "description": "A Square gift card." }, { "name": "APPOINTMENTS_SERVICE", "description": "A service that can be booked using the Square Appointments app." }, { "name": "FOOD_AND_BEV", "description": "A food or beverage item that can be sold by restaurants and other food venues." }, { "name": "EVENT", "description": "An event which tickets can be sold for, including location, address, and times." }, { "name": "DIGITAL", "description": "A digital item like an ebook or song." }, { "name": "DONATION", "description": "A donation which site visitors can send for any cause." }, { "name": "LEGACY_SQUARE_ONLINE_SERVICE", "description": "A legacy Square Online service that is manually fulfilled. This corresponds to the `Other` item type displayed in the Square Seller Dashboard and Square POS apps." }, { "name": "LEGACY_SQUARE_ONLINE_MEMBERSHIP", "description": "A legacy Square Online membership that is manually fulfilled. This corresponds to the `Membership` item type displayed in the Square Seller Dashboard and Square POS apps." } ], "description": "The type of a CatalogItem. Connect V2 only allows the creation of `REGULAR` or `APPOINTMENTS_SERVICE` items.", "x-release-status": "PUBLIC" }, "CatalogItemVariation": { "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\nitem variation and can have at most 250 item variations.\n\nAn 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\nnumber of the variation, or both. For example, when a variation representing wine is stocked and sold by the bottle, the variation is both\nstockable 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\nvariation is sellable, but not stockable. To accurately keep track of the wine's inventory count at any time, the sellable count must be\nconverted to stockable count. Typically, the seller defines this unit conversion. For example, 1 bottle equals 5 glasses. The Square API exposes\nthe `stockable_conversion` property on the variation to specify the conversion. Thus, when two glasses of the wine are sold, the sellable count\ndecreases by 2, and the stockable count automatically decreases by 0.4 bottle according to the conversion.", "x-release-status": "PUBLIC", "properties": { "item_id": { "type": [ "string", "null" ], "description": "The ID of the `CatalogItem` associated with this item variation." }, "name": { "type": [ "string", "null" ], "description": "The item variation's name. This is a searchable attribute for use in applicable query filters.\n\nIts value has a maximum length of 255 Unicode code points. However, when the parent [item](entity:CatalogItem)\nuses [item options](entity:CatalogItemOption), this attribute is auto-generated, read-only, and can be\nlonger than 255 Unicode code points." }, "sku": { "type": [ "string", "null" ], "description": "The item variation's SKU, if any. This is a searchable attribute for use in applicable query filters." }, "upc": { "type": [ "string", "null" ], "description": "The universal product code (UPC) of the item variation, if any. This is a searchable attribute for use in applicable query filters.\n\nThe value of this attribute should be a number of 12-14 digits long. This restriction is enforced on the Square Seller Dashboard,\nSquare Point of Sale or Retail Point of Sale apps, where this attribute shows in the GTIN field. If a non-compliant UPC value is assigned\nto this attribute using the API, the value is not editable on the Seller Dashboard, Square Point of Sale or Retail Point of Sale apps\nunless it is updated to fit the expected format." }, "ordinal": { "type": "integer", "description": "The order in which this item variation should be displayed. This value is read-only. On writes, the ordinal\nfor each item variation within a parent `CatalogItem` is set according to the item variations's\nposition. On reads, the value is not guaranteed to be sequential or unique.", "readOnly": true }, "pricing_type": { "$ref": "#/$defs/CatalogPricingType", "description": "Indicates whether the item variation's price is fixed or determined at the time\nof sale.\nSee [CatalogPricingType](#type-catalogpricingtype) for possible values" }, "price_money": { "$ref": "#/$defs/Money", "description": "The item variation's price, if fixed pricing is used." }, "location_overrides": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/ItemVariationLocationOverrides" }, "description": "Per-location price and inventory overrides." }, "track_inventory": { "type": [ "boolean", "null" ], "description": "If `true`, inventory tracking is active for the variation." }, "inventory_alert_type": { "$ref": "#/$defs/InventoryAlertType", "description": "Indicates whether the item variation displays an alert when its inventory quantity is less than or equal\nto its `inventory_alert_threshold`.\nSee [InventoryAlertType](#type-inventoryalerttype) for possible values" }, "inventory_alert_threshold": { "type": [ "integer", "null" ], "description": "If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type`\nis `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard.\n\nThis value is always an integer.", "format": "int64" }, "user_data": { "type": [ "string", "null" ], "description": "Arbitrary user metadata to associate with the item variation. This attribute value length is of Unicode code points.", "maxLength": 255 }, "service_duration": { "type": [ "integer", "null" ], "description": "If the `CatalogItem` that owns this item variation is of type\n`APPOINTMENTS_SERVICE`, then this is the duration of the service in milliseconds. For\nexample, a 30 minute appointment would have the value `1800000`, which is equal to\n30 (minutes) * 60 (seconds per minute) * 1000 (milliseconds per second).", "format": "int64" }, "available_for_booking": { "type": [ "boolean", "null" ], "description": "If the `CatalogItem` that owns this item variation is of type\n`APPOINTMENTS_SERVICE`, a bool representing whether this service is available for booking.", "x-release-status": "BETA" }, "item_option_values": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CatalogItemOptionValueForItemVariation" }, "description": "List of item option values associated with this item variation. Listed\nin the same order as the item options of the parent item." }, "measurement_unit_id": { "type": [ "string", "null" ], "description": "ID of the ‘CatalogMeasurementUnit’ that is used to measure the quantity\nsold of this item variation. If left unset, the item will be sold in\nwhole quantities." }, "sellable": { "type": [ "boolean", "null" ], "description": "Whether this variation can be sold. The inventory count of a sellable variation indicates\nthe number of units available for sale. When a variation is both stockable and sellable,\nits sellable inventory count can be smaller than or equal to its stockable count.", "x-release-status": "BETA" }, "stockable": { "type": [ "boolean", "null" ], "description": "Whether stock is counted directly on this variation (TRUE) or only on its components (FALSE).\nWhen a variation is both stockable and sellable, the inventory count of a stockable variation keeps track of the number of units of this variation in stock\nand is not an indicator of the number of units of the variation that can be sold.", "x-release-status": "BETA" }, "image_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The IDs of images associated with this `CatalogItemVariation` instance.\nThese images will be shown to customers in Square Online Store." }, "team_member_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tokens of employees that can perform the service represented by this variation. Only valid for\nvariations of type `APPOINTMENTS_SERVICE`.", "x-release-status": "BETA" }, "stockable_conversion": { "$ref": "#/$defs/CatalogStockConversion", "description": "The unit conversion rule, as prescribed by the [CatalogStockConversion](entity:CatalogStockConversion) type,\nthat describes how this non-stockable (i.e., sellable/receivable) item variation is converted\nto/from the stockable item variation sharing the same parent item. With the stock conversion,\nyou can accurately track inventory when an item variation is sold in one unit, but stocked in\nanother unit.", "x-release-status": "BETA" } } }, "CatalogMeasurementUnit": { "type": "object", "description": "Represents the unit used to measure a `CatalogItemVariation` and\nspecifies the precision for decimal quantities.", "x-release-status": "PUBLIC", "properties": { "measurement_unit": { "$ref": "#/$defs/MeasurementUnit", "description": "Indicates the unit used to measure the quantity of a catalog item variation." }, "precision": { "type": [ "integer", "null" ], "description": "An integer between 0 and 5 that represents the maximum number of\npositions allowed after the decimal in quantities measured with this unit.\nFor example:\n\n- if the precision is 0, the quantity can be 1, 2, 3, etc.\n- if the precision is 1, the quantity can be 0.1, 0.2, etc.\n- if the precision is 2, the quantity can be 0.01, 0.12, etc.\n\nDefault: 3" } } }, "CatalogModifier": { "type": "object", "description": "A modifier applicable to items at the time of sale. An example of a modifier is a Cheese add-on to a Burger item.", "x-release-status": "PUBLIC", "properties": { "name": { "type": [ "string", "null" ], "description": "The modifier name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "maxLength": 255 }, "price_money": { "$ref": "#/$defs/Money", "description": "The modifier price." }, "ordinal": { "type": [ "integer", "null" ], "description": "Determines where this `CatalogModifier` appears in the `CatalogModifierList`." }, "modifier_list_id": { "type": [ "string", "null" ], "description": "The ID of the `CatalogModifierList` associated with this modifier." }, "location_overrides": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/ModifierLocationOverrides" }, "description": "Location-specific price overrides." }, "image_id": { "type": [ "string", "null" ], "description": "The ID of the image associated with this `CatalogModifier` instance.\nCurrently this image is not displayed by Square, but is free to be displayed in 3rd party applications.", "x-release-status": "BETA" } } }, "CatalogModifierList": { "type": "object", "description": "For a text-based modifier, this encapsulates the modifier's text when its `modifier_type` is `TEXT`. \nFor example, to sell T-shirts with custom prints, a text-based modifier can be used to capture the buyer-supplied \ntext string to be selected for the T-shirt at the time of sale.\n\nFor non text-based modifiers, this encapsulates a non-empty list of modifiers applicable to items \nat the time of sale. Each element of the modifier list is a `CatalogObject` instance of the `MODIFIER` type. \nFor example, a \"Condiments\" modifier list applicable to a \"Hot Dog\" item\nmay contain \"Ketchup\", \"Mustard\", and \"Relish\" modifiers. \n\nA non text-based modifier can be applied to the modified item once or multiple times, if the `selection_type` field \nis set to `SINGLE` or `MULTIPLE`, respectively. On the other hand, a text-based modifier can be applied to the item \nonly once and the `selection_type` field is always set to `SINGLE`.", "x-release-status": "PUBLIC", "properties": { "name": { "type": [ "string", "null" ], "description": "The name of the `CatalogModifierList` instance. This is a searchable attribute for use in applicable query filters, and its value length is of \nUnicode code points.", "maxLength": 255 }, "ordinal": { "type": [ "integer", "null" ], "description": "The position of this `CatalogModifierList` within a list of `CatalogModifierList` instances." }, "selection_type": { "$ref": "#/$defs/CatalogModifierListSelectionType", "description": "Indicates whether a single (`SINGLE`) or multiple (`MULTIPLE`) modifiers from the list\ncan be applied to a single `CatalogItem`.\n\nFor text-based modifiers, the `selection_type` attribute is always `SINGLE`. The other value is ignored.\nSee [CatalogModifierListSelectionType](#type-catalogmodifierlistselectiontype) for possible values" }, "modifiers": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CatalogObject" }, "description": "A non-empty list of `CatalogModifier` objects to be included in the `CatalogModifierList`, \nfor non text-based modifiers when the `modifier_type` attribute is `LIST`. Each element of this list \nis a `CatalogObject` instance of the `MODIFIER` type, containing the following attributes:\n```\n{\n\"id\": \"{{catalog_modifier_id}}\",\n\"type\": \"MODIFIER\", \n\"modifier_data\": {{a CatalogModifier instance>}} \n}\n```" }, "image_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The IDs of images associated with this `CatalogModifierList` instance.\nCurrently these images are not displayed on Square products, but may be displayed in 3rd-party applications." }, "modifier_type": { "$ref": "#/$defs/CatalogModifierListModifierType", "description": "The type of the modifier. \n\nWhen this `modifier_type` value is `TEXT`, the `CatalogModifierList` represents a text-based modifier. \nWhen this `modifier_type` value is `LIST`, the `CatalogModifierList` contains a list of `CatalogModifier` objects.\nSee [CatalogModifierListModifierType](#type-catalogmodifierlistmodifiertype) for possible values", "x-release-status": "BETA" }, "max_length": { "type": [ "integer", "null" ], "description": "The maximum length, in Unicode points, of the text string of the text-based modifier as represented by \nthis `CatalogModifierList` object with the `modifier_type` set to `TEXT`.", "x-release-status": "BETA" }, "text_required": { "type": [ "boolean", "null" ], "description": "Whether the text string must be a non-empty string (`true`) or not (`false`) for a text-based modifier\nas represented by this `CatalogModifierList` object with the `modifier_type` set to `TEXT`.", "x-release-status": "BETA" }, "internal_name": { "type": [ "string", "null" ], "description": "A note for internal use by the business. \n\nFor example, for a text-based modifier applied to a T-shirt item, if the buyer-supplied text of \"Hello, Kitty!\" \nis to be printed on the T-shirt, this `internal_name` attribute can be \"Use italic face\" as \nan instruction for the business to follow. \n\nFor non text-based modifiers, this `internal_name` attribute can be \nused to include SKUs, internal codes, or supplemental descriptions for internal use.", "maxLength": 512, "x-release-status": "BETA" } } }, "CatalogModifierListModifierType": { "type": "string", "enum": [ "LIST", "TEXT" ], "x-enum-elements": [ { "name": "LIST", "description": "The `CatalogModifierList` instance is a non-empty list of non text-based modifiers." }, { "name": "TEXT", "description": "The `CatalogModifierList` instance is a single text-based modifier." } ], "description": "Defines the type of `CatalogModifierList`.", "x-release-status": "BETA" }, "CatalogModifierListSelectionType": { "type": "string", "enum": [ "SINGLE", "MULTIPLE" ], "x-enum-elements": [ { "name": "SINGLE", "description": "Indicates that a CatalogModifierList allows only a\nsingle CatalogModifier to be selected." }, { "name": "MULTIPLE", "description": "Indicates that a CatalogModifierList allows multiple\nCatalogModifier to be selected." } ], "description": "Indicates whether a CatalogModifierList supports multiple selections.", "x-release-status": "PUBLIC" }, "CatalogModifierOverride": { "type": "object", "description": "Options to control how to override the default behavior of the specified modifier.", "x-release-status": "PUBLIC", "required": [ "modifier_id" ], "properties": { "modifier_id": { "type": "string", "description": "The ID of the `CatalogModifier` whose default behavior is being overridden.", "minLength": 1 }, "on_by_default": { "type": [ "boolean", "null" ], "description": "If `true`, this `CatalogModifier` should be selected by default for this `CatalogItem`." } } }, "CatalogObject": { "type": "object", "description": "The wrapper object for the catalog entries of a given object type.\n\nDepending on the `type` attribute value, a `CatalogObject` instance assumes a type-specific data to yield the corresponding type of catalog object.\n\nFor 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.\n\nIn 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.\n\nFor a more detailed discussion of the Catalog data model, please see the\n[Design a Catalog](https://developer.squareup.com/docs/catalog-api/design-a-catalog) guide.", "x-release-status": "PUBLIC", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/$defs/CatalogObjectType", "description": "The type of this object. Each object type has expected\nproperties expressed in a structured format within its corresponding `*_data` field below.\nSee [CatalogObjectType](#type-catalogobjecttype) for possible values" }, "id": { "type": "string", "description": "An identifier to reference this object in the catalog. When a new `CatalogObject`\nis inserted, the client should set the id to a temporary identifier starting with\na \"`#`\" character. Other objects being inserted or updated within the same request\nmay use this identifier to refer to the new object.\n\nWhen the server receives the new object, it will supply a unique identifier that\nreplaces the temporary identifier for all future references.", "minLength": 1 }, "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\"`\nwould indicate the UTC time (denoted by `Z`) of August 15, 2016 at 23:59:33 and 123 milliseconds.", "readOnly": true }, "version": { "type": "integer", "description": "The version of the object. When updating an object, the version supplied\nmust match the version in the database, otherwise the write will be rejected as conflicting.", "format": "int64" }, "is_deleted": { "type": [ "boolean", "null" ], "description": "If `true`, the object has been deleted from the database. Must be `false` for new objects\nbeing inserted. When deleted, the `updated_at` field will equal the deletion time." }, "custom_attribute_values": { "type": [ "object", "null" ], "additionalProperties": { "$ref": "#/$defs/CatalogCustomAttributeValue" }, "description": "A map (key-value pairs) of application-defined custom attribute values. The value of a key-value pair\nis a [CatalogCustomAttributeValue](entity:CatalogCustomAttributeValue) object. The key is the `key` attribute\nvalue defined in the associated [CatalogCustomAttributeDefinition](entity:CatalogCustomAttributeDefinition)\nobject defined by the application making the request.\n\nIf the `CatalogCustomAttributeDefinition` object is\ndefined by another application, the `CatalogCustomAttributeDefinition`'s key attribute value is prefixed by\nthe defining application ID. For example, if the `CatalogCustomAttributeDefinition` has a `key` attribute of\n`\"cocoa_brand\"` and the defining application ID is `\"abcd1234\"`, the key in the map is `\"abcd1234:cocoa_brand\"`\nif the application making the request is different from the application defining the custom attribute definition.\nOtherwise, the key used in the map is simply `\"cocoa_brand\"`.\n\nApplication-defined custom attributes are set at a global (location-independent) level.\nCustom attribute values are intended to store additional information about a catalog object\nor associations with an entity in another system. Do not use custom attributes\nto store any sensitive information (personally identifiable information, card details, etc.)." }, "catalog_v1_ids": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CatalogV1Id" }, "description": "The Connect v1 IDs for this object at each location where it is present, where they\ndiffer from the object's Connect V2 ID. The field will only be present for objects that\nhave been created or modified by legacy APIs." }, "present_at_all_locations": { "type": [ "boolean", "null" ], "description": "If `true`, this object is present at all locations (including future locations), except where specified in\nthe `absent_at_location_ids` field. If `false`, this object is not present at any locations (including future locations),\nexcept where specified in the `present_at_location_ids` field. If not specified, defaults to `true`." }, "present_at_location_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "A list of locations where the object is present, even if `present_at_all_locations` is `false`.\nThis can include locations that are deactivated." }, "absent_at_location_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "A list of locations where the object is not present, even if `present_at_all_locations` is `true`.\nThis can include locations that are deactivated." }, "item_data": { "$ref": "#/$defs/CatalogItem", "description": "Structured data for a `CatalogItem`, set for CatalogObjects of type `ITEM`." }, "category_data": { "$ref": "#/$defs/CatalogCategory", "description": "Structured data for a `CatalogCategory`, set for CatalogObjects of type `CATEGORY`." }, "item_variation_data": { "$ref": "#/$defs/CatalogItemVariation", "description": "Structured data for a `CatalogItemVariation`, set for CatalogObjects of type `ITEM_VARIATION`." }, "tax_data": { "$ref": "#/$defs/CatalogTax", "description": "Structured data for a `CatalogTax`, set for CatalogObjects of type `TAX`." }, "discount_data": { "$ref": "#/$defs/CatalogDiscount", "description": "Structured data for a `CatalogDiscount`, set for CatalogObjects of type `DISCOUNT`." }, "modifier_list_data": { "$ref": "#/$defs/CatalogModifierList", "description": "Structured data for a `CatalogModifierList`, set for CatalogObjects of type `MODIFIER_LIST`." }, "modifier_data": { "$ref": "#/$defs/CatalogModifier", "description": "Structured data for a `CatalogModifier`, set for CatalogObjects of type `MODIFIER`." }, "time_period_data": { "$ref": "#/$defs/CatalogTimePeriod", "description": "Structured data for a `CatalogTimePeriod`, set for CatalogObjects of type `TIME_PERIOD`." }, "product_set_data": { "$ref": "#/$defs/CatalogProductSet", "description": "Structured data for a `CatalogProductSet`, set for CatalogObjects of type `PRODUCT_SET`." }, "pricing_rule_data": { "$ref": "#/$defs/CatalogPricingRule", "description": "Structured data for a `CatalogPricingRule`, set for CatalogObjects of type `PRICING_RULE`.\nA `CatalogPricingRule` object often works with a `CatalogProductSet` object or a `CatalogTimePeriod` object." }, "image_data": { "$ref": "#/$defs/CatalogImage", "description": "Structured data for a `CatalogImage`, set for CatalogObjects of type `IMAGE`." }, "measurement_unit_data": { "$ref": "#/$defs/CatalogMeasurementUnit", "description": "Structured data for a `CatalogMeasurementUnit`, set for CatalogObjects of type `MEASUREMENT_UNIT`." }, "subscription_plan_data": { "$ref": "#/$defs/CatalogSubscriptionPlan", "description": "Structured data for a `CatalogSubscriptionPlan`, set for CatalogObjects of type `SUBSCRIPTION_PLAN`." }, "item_option_data": { "$ref": "#/$defs/CatalogItemOption", "description": "Structured data for a `CatalogItemOption`, set for CatalogObjects of type `ITEM_OPTION`." }, "item_option_value_data": { "$ref": "#/$defs/CatalogItemOptionValue", "description": "Structured data for a `CatalogItemOptionValue`, set for CatalogObjects of type `ITEM_OPTION_VAL`." }, "custom_attribute_definition_data": { "$ref": "#/$defs/CatalogCustomAttributeDefinition", "description": "Structured data for a `CatalogCustomAttributeDefinition`, set for CatalogObjects of type `CUSTOM_ATTRIBUTE_DEFINITION`." }, "quick_amounts_settings_data": { "$ref": "#/$defs/CatalogQuickAmountsSettings", "description": "Structured data for a `CatalogQuickAmountsSettings`, set for CatalogObjects of type `QUICK_AMOUNTS_SETTINGS`.", "x-release-status": "BETA" }, "subscription_plan_variation_data": { "$ref": "#/$defs/CatalogSubscriptionPlanVariation", "description": "Structured data for a `CatalogSubscriptionPlanVariation`, set for CatalogObjects of type `SUBSCRIPTION_PLAN_VARIATION`." }, "availability_period_data": { "$ref": "#/$defs/CatalogAvailabilityPeriod", "description": "Structured data for a `CatalogAvailabilityPeriod`, set for CatalogObjects of type `AVAILABILITY_PERIOD`." } } }, "CatalogObjectCategory": { "type": "object", "description": "A category that can be assigned to an item or a parent category that can be assigned \nto another category. For example, a clothing category can be assigned to a t-shirt item or \nbe made as the parent category to the pants category.", "x-release-status": "BETA", "properties": { "id": { "type": "string", "description": "The ID of the object's category." }, "ordinal": { "type": [ "integer", "null" ], "description": "The order of the object within the context of the category.", "format": "int64" } } }, "CatalogObjectType": { "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" ], "x-enum-elements": [ { "name": "ITEM", "description": "The `CatalogObject` instance is of the [CatalogItem](entity:CatalogItem) type and represents an item. The item-specific data\nmust be set on the `item_data` field." }, { "name": "IMAGE", "description": "The `CatalogObject` instance is of the [CatalogImage](entity:CatalogImage) type and represents an image. The image-specific data\nmust be set on the `image_data` field." }, { "name": "CATEGORY", "description": "The `CatalogObject` instance is of the [CatalogCategory](entity:CatalogCategory) type and represents a category. The category-specific data\nmust be set on the `category_data` field." }, { "name": "ITEM_VARIATION", "description": "The `CatalogObject` instance is of the [CatalogItemVariation](entity:CatalogItemVariation) type and represents an item variation, also referred to as variation.\nThe item variation-specific data must be set on the `item_variation_data` field." }, { "name": "TAX", "description": "The `CatalogObject` instance is of the [CatalogTax](entity:CatalogTax) type and represents a tax. The tax-specific data\nmust be set on the `tax_data` field." }, { "name": "DISCOUNT", "description": "The `CatalogObject` instance is of the [CatalogDiscount](entity:CatalogDiscount) type and represents a discount. The discount-specific data\nmust be set on the `discount_data` field." }, { "name": "MODIFIER_LIST", "description": "The `CatalogObject` instance is of the [CatalogModifierList](entity:CatalogModifierList) type and represents a modifier list.\nThe modifier-list-specific data must be set on the `modifier_list_data` field." }, { "name": "MODIFIER", "description": "The `CatalogObject` instance is of the [CatalogModifier](entity:CatalogModifier) type and represents a modifier. The modifier-specific data\nmust be set on the `modifier_data` field." }, { "name": "PRICING_RULE", "description": "The `CatalogObject` instance is of the [CatalogPricingRule](entity:CatalogPricingRule) type and represents a pricing rule. The pricing-rule-specific data\nmust be set on the `pricing_rule_data` field." }, { "name": "PRODUCT_SET", "description": "The `CatalogObject` instance is of the [CatalogProductSet](entity:CatalogProductSet) type and represents a product set.\nThe product-set-specific data will be stored in the `product_set_data` field." }, { "name": "TIME_PERIOD", "description": "The `CatalogObject` instance is of the [CatalogTimePeriod](entity:CatalogTimePeriod) type and represents a time period.\nThe time-period-specific data must be set on the `time_period_data` field." }, { "name": "MEASUREMENT_UNIT", "description": "The `CatalogObject` instance is of the [CatalogMeasurementUnit](entity:CatalogMeasurementUnit) type and represents a measurement unit specifying the unit of\nmeasure and precision in which an item variation is sold. The measurement-unit-specific data must set on the `measurement_unit_data` field." }, { "name": "SUBSCRIPTION_PLAN_VARIATION", "description": "The `CatalogObject` instance is of the [CatalogSubscriptionPlan](entity:CatalogSubscriptionPlan) type and represents a subscription plan.\nThe subscription-plan-specific data must be stored on the `subscription_plan_data` field." }, { "name": "ITEM_OPTION", "description": "The `CatalogObject` instance is of the [CatalogItemOption](entity:CatalogItemOption) type and represents a list of options (such as a color or size of a T-shirt)\nthat can be assigned to item variations. The item-option-specific data must be on the `item_option_data` field." }, { "name": "ITEM_OPTION_VAL", "description": "The `CatalogObject` instance is of the [CatalogItemOptionValue](entity:CatalogItemOptionValue) type and represents a value associated with one or more item options.\nFor example, an item option of \"Size\" may have item option values such as \"Small\" or \"Medium\".\nThe item-option-value-specific data must be on the `item_option_value_data` field." }, { "name": "CUSTOM_ATTRIBUTE_DEFINITION", "description": "The `CatalogObject` instance is of the [CatalogCustomAttributeDefinition](entity:CatalogCustomAttributeDefinition) type and represents the definition of a custom attribute.\nThe custom-attribute-definition-specific data must be set on the `custom_attribute_definition_data` field." }, { "name": "QUICK_AMOUNTS_SETTINGS", "description": "The `CatalogObject` instance is of the [CatalogQuickAmountsSettings](entity:CatalogQuickAmountsSettings) type and represents settings to configure preset charges for quick payments at each location.\nFor example, a location may have a list of both AUTO and MANUAL quick amounts that are set to DISABLED.\nThe quick-amounts-settings-specific data must be set on the `quick_amounts_settings_data` field." }, { "name": "SUBSCRIPTION_PLAN", "description": "The `CatalogObject` instance is of the [CatalogSubscriptionPlan](entity:CatalogSubscriptionPlan) type and represents a subscription plan.\nThe subscription plan specific data must be stored on the `subscription_plan_data` field." }, { "name": "AVAILABILITY_PERIOD", "description": "The `CatalogObject` instance is of the [CatalogAvailabilityPeriod](entity:CatalogAvailabilityPeriod) type and represents an availability period.\nThe availability period specific data must be stored on the `availability_period_data` field." } ], "description": "Possible types of CatalogObjects returned from the catalog, each\ncontaining type-specific properties in the `*_data` field corresponding to the specified object type.", "x-release-status": "PUBLIC" }, "CatalogPricingRule": { "type": "object", "description": "Defines how discounts are automatically applied to a set of items that match the pricing rule\nduring the active time period.", "x-release-status": "PUBLIC", "properties": { "name": { "type": [ "string", "null" ], "description": "User-defined name for the pricing rule. For example, \"Buy one get one\nfree\" or \"10% off\"." }, "time_period_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "A list of unique IDs for the catalog time periods when\nthis pricing rule is in effect. If left unset, the pricing rule is always\nin effect." }, "discount_id": { "type": [ "string", "null" ], "description": "Unique ID for the `CatalogDiscount` to take off\nthe price of all matched items." }, "match_products_id": { "type": [ "string", "null" ], "description": "Unique ID for the `CatalogProductSet` that will be matched by this rule. A match rule\nmatches within the entire cart, and can match multiple times. This field will always be set." }, "apply_products_id": { "type": [ "string", "null" ], "description": "__Deprecated__: Please use the `exclude_products_id` field to apply\nan exclude set instead. Exclude sets allow better control over quantity\nranges and offer more flexibility for which matched items receive a discount.\n\n`CatalogProductSet` to apply the pricing to.\nAn apply rule matches within the subset of the cart that fits the match rules (the match set).\nAn apply rule can only match once in the match set.\nIf not supplied, the pricing will be applied to all products in the match set.\nOther products retain their base price, or a price generated by other rules.", "x-release-status": "DEPRECATED" }, "exclude_products_id": { "type": [ "string", "null" ], "description": "`CatalogProductSet` to exclude from the pricing rule.\nAn exclude rule matches within the subset of the cart that fits the match rules (the match set).\nAn exclude rule can only match once in the match set.\nIf not supplied, the pricing will be applied to all products in the match set.\nOther products retain their base price, or a price generated by other rules." }, "valid_from_date": { "type": [ "string", "null" ], "description": "Represents the date the Pricing Rule is valid from. Represented in RFC 3339 full-date format (YYYY-MM-DD)." }, "valid_from_local_time": { "type": [ "string", "null" ], "description": "Represents the local time the pricing rule should be valid from. Represented in RFC 3339 partial-time format\n(HH:MM:SS). Partial seconds will be truncated." }, "valid_until_date": { "type": [ "string", "null" ], "description": "Represents the date the Pricing Rule is valid until. Represented in RFC 3339 full-date format (YYYY-MM-DD)." }, "valid_until_local_time": { "type": [ "string", "null" ], "description": "Represents the local time the pricing rule should be valid until. Represented in RFC 3339 partial-time format\n(HH:MM:SS). Partial seconds will be truncated." }, "exclude_strategy": { "$ref": "#/$defs/ExcludeStrategy", "description": "If an `exclude_products_id` was given, controls which subset of matched\nproducts is excluded from any discounts.\n\nDefault value: `LEAST_EXPENSIVE`\nSee [ExcludeStrategy](#type-excludestrategy) for possible values" }, "minimum_order_subtotal_money": { "$ref": "#/$defs/Money", "description": "The minimum order subtotal (before discounts or taxes are applied)\nthat must be met before this rule may be applied." }, "customer_group_ids_any": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "A list of IDs of customer groups, the members of which are eligible for discounts specified in this pricing rule.\nNotice that a group ID is generated by the Customers API.\nIf this field is not set, the specified discount applies to matched products sold to anyone whether the buyer\nhas a customer profile created or not. If this `customer_group_ids_any` field is set, the specified discount\napplies only to matched products sold to customers belonging to the specified customer groups." } } }, "CatalogPricingType": { "type": "string", "enum": [ "FIXED_PRICING", "VARIABLE_PRICING" ], "x-enum-elements": [ { "name": "FIXED_PRICING", "description": "The catalog item variation's price is fixed." }, { "name": "VARIABLE_PRICING", "description": "The catalog item variation's price is entered at the time of sale." } ], "description": "Indicates whether the price of a CatalogItemVariation should be entered manually at the time of sale.", "x-release-status": "PUBLIC" }, "CatalogProductSet": { "type": "object", "description": "Represents a collection of catalog objects for the purpose of applying a\n`PricingRule`. Including a catalog object will include all of its subtypes.\nFor example, including a category in a product set will include all of its\nitems and associated item variations in the product set. Including an item in\na product set will also include its item variations.", "x-release-status": "PUBLIC", "properties": { "name": { "type": [ "string", "null" ], "description": "User-defined name for the product set. For example, \"Clearance Items\"\nor \"Winter Sale Items\"." }, "product_ids_any": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": " Unique IDs for any `CatalogObject` included in this product set. Any\nnumber of these catalog objects can be in an order for a pricing rule to apply.\n\nThis can be used with `product_ids_all` in a parent `CatalogProductSet` to\nmatch groups of products for a bulk discount, such as a discount for an\nentree and side combo.\n\nOnly one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.\n\nMax: 500 catalog object IDs." }, "product_ids_all": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Unique IDs for any `CatalogObject` included in this product set.\nAll objects in this set must be included in an order for a pricing rule to apply.\n\nOnly one of `product_ids_all`, `product_ids_any`, or `all_products` can be set.\n\nMax: 500 catalog object IDs." }, "quantity_exact": { "type": [ "integer", "null" ], "description": "If set, there must be exactly this many items from `products_any` or `products_all`\nin the cart for the discount to apply.\n\nCannot be combined with either `quantity_min` or `quantity_max`.", "format": "int64" }, "quantity_min": { "type": [ "integer", "null" ], "description": "If set, there must be at least this many items from `products_any` or `products_all`\nin a cart for the discount to apply. See `quantity_exact`. Defaults to 0 if\n`quantity_exact`, `quantity_min` and `quantity_max` are all unspecified.", "format": "int64" }, "quantity_max": { "type": [ "integer", "null" ], "description": "If set, the pricing rule will apply to a maximum of this many items from\n`products_any` or `products_all`.", "format": "int64" }, "all_products": { "type": [ "boolean", "null" ], "description": "If set to `true`, the product set will include every item in the catalog.\nOnly one of `product_ids_all`, `product_ids_any`, or `all_products` can be set." } } }, "CatalogQuickAmount": { "type": "object", "description": "Represents a Quick Amount in the Catalog.", "x-release-status": "BETA", "required": [ "type", "amount" ], "properties": { "type": { "$ref": "#/$defs/CatalogQuickAmountType", "description": "Represents the type of the Quick Amount.\nSee [CatalogQuickAmountType](#type-catalogquickamounttype) for possible values" }, "amount": { "$ref": "#/$defs/Money", "description": "Represents the actual amount of the Quick Amount with Money type." }, "score": { "type": [ "integer", "null" ], "description": "Describes the ranking of the Quick Amount provided by machine learning model, in the range [0, 100].\nMANUAL type amount will always have score = 100.", "format": "int64" }, "ordinal": { "type": [ "integer", "null" ], "description": "The order in which this Quick Amount should be displayed.", "format": "int64" } } }, "CatalogQuickAmountType": { "type": "string", "enum": [ "QUICK_AMOUNT_TYPE_MANUAL", "QUICK_AMOUNT_TYPE_AUTO" ], "x-enum-elements": [ { "name": "QUICK_AMOUNT_TYPE_MANUAL", "description": "Quick Amount is created manually by the seller." }, { "name": "QUICK_AMOUNT_TYPE_AUTO", "description": "Quick Amount is generated automatically by machine learning algorithms." } ], "description": "Determines the type of a specific Quick Amount.", "x-release-status": "BETA" }, "CatalogQuickAmountsSettings": { "type": "object", "description": "A parent Catalog Object model represents a set of Quick Amounts and the settings control the amounts.", "x-release-status": "BETA", "required": [ "option" ], "properties": { "option": { "$ref": "#/$defs/CatalogQuickAmountsSettingsOption", "description": "Represents the option seller currently uses on Quick Amounts.\nSee [CatalogQuickAmountsSettingsOption](#type-catalogquickamountssettingsoption) for possible values" }, "eligible_for_auto_amounts": { "type": [ "boolean", "null" ], "description": "Represents location's eligibility for auto amounts\nThe boolean should be consistent with whether there are AUTO amounts in the `amounts`." }, "amounts": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CatalogQuickAmount" }, "description": "Represents a set of Quick Amounts at this location." } } }, "CatalogQuickAmountsSettingsOption": { "type": "string", "enum": [ "DISABLED", "MANUAL", "AUTO" ], "x-enum-elements": [ { "name": "DISABLED", "description": "Option for seller to disable Quick Amounts." }, { "name": "MANUAL", "description": "Option for seller to choose manually created Quick Amounts." }, { "name": "AUTO", "description": "Option for seller to choose automatically created Quick Amounts." } ], "description": "Determines a seller's option on Quick Amounts feature.", "x-release-status": "BETA" }, "CatalogStockConversion": { "type": "object", "description": "Represents the rule of conversion between a stockable [CatalogItemVariation](entity:CatalogItemVariation)\nand a non-stockable sell-by or receive-by `CatalogItemVariation` that\nshare the same underlying stock.", "x-release-status": "BETA", "required": [ "stockable_item_variation_id", "stockable_quantity", "nonstockable_quantity" ], "properties": { "stockable_item_variation_id": { "type": "string", "description": "References to the stockable [CatalogItemVariation](entity:CatalogItemVariation)\nfor this stock conversion. Selling, receiving or recounting the non-stockable `CatalogItemVariation`\ndefined with a stock conversion results in adjustments of this stockable `CatalogItemVariation`.\nThis immutable field must reference a stockable `CatalogItemVariation`\nthat shares the parent [CatalogItem](entity:CatalogItem) of the converted `CatalogItemVariation.`", "minLength": 1 }, "stockable_quantity": { "type": "string", "description": "The quantity of the stockable item variation (as identified by `stockable_item_variation_id`)\nequivalent to the non-stockable item variation quantity (as specified in `nonstockable_quantity`)\nas defined by this stock conversion. It accepts a decimal number in a string format that can take\nup to 10 digits before the decimal point and up to 5 digits after the decimal point.", "minLength": 1, "maxLength": 16 }, "nonstockable_quantity": { "type": "string", "description": "The converted equivalent quantity of the non-stockable [CatalogItemVariation](entity:CatalogItemVariation)\nin its measurement unit. The `stockable_quantity` value and this `nonstockable_quantity` value together\ndefine the conversion ratio between stockable item variation and the non-stockable item variation.\nIt accepts a decimal number in a string format that can take up to 10 digits before the decimal point\nand up to 5 digits after the decimal point.", "minLength": 1, "maxLength": 16 } } }, "CatalogSubscriptionPlan": { "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.\nFor more information, see [Subscription Plans and Variations](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations).", "x-release-status": "PUBLIC", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the plan." }, "phases": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/SubscriptionPhase" }, "description": "A list of SubscriptionPhase containing the [SubscriptionPhase](entity:SubscriptionPhase) for this plan.\nThis field it required. Not including this field will throw a REQUIRED_FIELD_MISSING error" }, "subscription_plan_variations": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CatalogObject" }, "description": "The list of subscription plan variations available for this product" }, "eligible_item_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The list of IDs of `CatalogItems` that are eligible for subscription by this SubscriptionPlan's variations." }, "eligible_category_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The list of IDs of `CatalogCategory` that are eligible for subscription by this SubscriptionPlan's variations." }, "all_items": { "type": [ "boolean", "null" ], "description": "If true, all items in the merchant's catalog are subscribable by this SubscriptionPlan." } } }, "CatalogSubscriptionPlanVariation": { "type": "object", "description": "Describes a subscription plan variation. A subscription plan variation represents how the subscription for a product or service is sold.\nFor more information, see [Subscription Plans and Variations](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations).", "x-release-status": "PUBLIC", "required": [ "name", "phases" ], "properties": { "name": { "type": "string", "description": "The name of the plan variation." }, "phases": { "type": "array", "items": { "$ref": "#/$defs/SubscriptionPhase" }, "description": "A list containing each [SubscriptionPhase](entity:SubscriptionPhase) for this plan variation." }, "subscription_plan_id": { "type": [ "string", "null" ], "description": "The id of the subscription plan, if there is one." }, "monthly_billing_anchor_date": { "type": [ "integer", "null" ], "description": "The day of the month the billing period starts.", "format": "int64", "minimum": 1, "maximum": 31 }, "can_prorate": { "type": [ "boolean", "null" ], "description": "Whether bills for this plan variation can be split for proration." }, "successor_plan_variation_id": { "type": [ "string", "null" ], "description": "The ID of a \"successor\" plan variation to this one. If the field is set, and this object is disabled at all\nlocations, it indicates that this variation is deprecated and the object identified by the successor ID be used in\nits stead." } } }, "CatalogTax": { "type": "object", "description": "A tax applicable to an item.", "x-release-status": "PUBLIC", "properties": { "name": { "type": [ "string", "null" ], "description": "The tax's name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.", "maxLength": 255 }, "calculation_phase": { "$ref": "#/$defs/TaxCalculationPhase", "description": "Whether the tax is calculated based on a payment's subtotal or total.\nSee [TaxCalculationPhase](#type-taxcalculationphase) for possible values" }, "inclusion_type": { "$ref": "#/$defs/TaxInclusionType", "description": "Whether the tax is `ADDITIVE` or `INCLUSIVE`.\nSee [TaxInclusionType](#type-taxinclusiontype) for possible values" }, "percentage": { "type": [ "string", "null" ], "description": "The percentage of the tax in decimal form, using a `'.'` as the decimal separator and without a `'%'` sign.\nA value of `7.5` corresponds to 7.5%. For a location-specific tax rate, contact the tax authority of the location or a tax consultant." }, "applies_to_custom_amounts": { "type": [ "boolean", "null" ], "description": "If `true`, the fee applies to custom amounts entered into the Square Point of Sale\napp that are not associated with a particular `CatalogItem`." }, "enabled": { "type": [ "boolean", "null" ], "description": "A Boolean flag to indicate whether the tax is displayed as enabled (`true`) in the Square Point of Sale app or not (`false`)." }, "applies_to_product_set_id": { "type": [ "string", "null" ], "description": "The ID of a `CatalogProductSet` object. If set, the tax is applicable to all products in the product set.", "x-release-status": "BETA" } } }, "CatalogTimePeriod": { "type": "object", "description": "Represents a time period - either a single period or a repeating period.", "x-release-status": "PUBLIC", "properties": { "event": { "type": [ "string", "null" ], "description": "An iCalendar (RFC 5545) [event](https://tools.ietf.org/html/rfc5545#section-3.6.1), which\nspecifies the name, timing, duration and recurrence of this time period.\n\nExample:\n\n```\nDTSTART:20190707T180000\nDURATION:P2H\nRRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR\n```\n\nOnly `SUMMARY`, `DTSTART`, `DURATION` and `RRULE` fields are supported.\n`DTSTART` must be in local (unzoned) time format. Note that while `BEGIN:VEVENT`\nand `END:VEVENT` is not required in the request. The response will always\ninclude them." } } }, "CatalogV1Id": { "type": "object", "description": "A Square API V1 identifier of an item, including the object ID and its associated location ID.", "x-release-status": "PUBLIC", "properties": { "catalog_v1_id": { "type": [ "string", "null" ], "description": "The ID for an object used in the Square API V1, if the object ID differs from the Square API V2 object ID." }, "location_id": { "type": [ "string", "null" ], "description": "The ID of the `Location` this Connect V1 ID is associated with." } } }, "CategoryPathToRootNode": { "type": "object", "description": "A node in the path from a retrieved category to its root node.", "x-release-status": "PUBLIC", "properties": { "category_id": { "type": [ "string", "null" ], "description": "The category's ID." }, "category_name": { "type": [ "string", "null" ], "description": "The category's name." } } }, "Currency": { "type": "string", "enum": [ "UNKNOWN_CURRENCY", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYR", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SLE", "SOS", "SRD", "SSP", "STD", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "USS", "UYI", "UYU", "UZS", "VEF", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XOF", "XPD", "XPF", "XPT", "XTS", "XXX", "YER", "ZAR", "ZMK", "ZMW", "BTC", "XUS" ], "x-enum-elements": [ { "name": "UNKNOWN_CURRENCY", "description": "Unknown currency" }, { "name": "AED", "description": "United Arab Emirates dirham" }, { "name": "AFN", "description": "Afghan afghani" }, { "name": "ALL", "description": "Albanian lek" }, { "name": "AMD", "description": "Armenian dram" }, { "name": "ANG", "description": "Netherlands Antillean guilder" }, { "name": "AOA", "description": "Angolan kwanza" }, { "name": "ARS", "description": "Argentine peso" }, { "name": "AUD", "description": "Australian dollar" }, { "name": "AWG", "description": "Aruban florin" }, { "name": "AZN", "description": "Azerbaijani manat" }, { "name": "BAM", "description": "Bosnia and Herzegovina convertible mark" }, { "name": "BBD", "description": "Barbados dollar" }, { "name": "BDT", "description": "Bangladeshi taka" }, { "name": "BGN", "description": "Bulgarian lev" }, { "name": "BHD", "description": "Bahraini dinar" }, { "name": "BIF", "description": "Burundian franc" }, { "name": "BMD", "description": "Bermudian dollar" }, { "name": "BND", "description": "Brunei dollar" }, { "name": "BOB", "description": "Boliviano" }, { "name": "BOV", "description": "Bolivian Mvdol" }, { "name": "BRL", "description": "Brazilian real" }, { "name": "BSD", "description": "Bahamian dollar" }, { "name": "BTN", "description": "Bhutanese ngultrum" }, { "name": "BWP", "description": "Botswana pula" }, { "name": "BYR", "description": "Belarusian ruble" }, { "name": "BZD", "description": "Belize dollar" }, { "name": "CAD", "description": "Canadian dollar" }, { "name": "CDF", "description": "Congolese franc" }, { "name": "CHE", "description": "WIR Euro" }, { "name": "CHF", "description": "Swiss franc" }, { "name": "CHW", "description": "WIR Franc" }, { "name": "CLF", "description": "Unidad de Fomento" }, { "name": "CLP", "description": "Chilean peso" }, { "name": "CNY", "description": "Chinese yuan" }, { "name": "COP", "description": "Colombian peso" }, { "name": "COU", "description": "Unidad de Valor Real" }, { "name": "CRC", "description": "Costa Rican colon" }, { "name": "CUC", "description": "Cuban convertible peso" }, { "name": "CUP", "description": "Cuban peso" }, { "name": "CVE", "description": "Cape Verdean escudo" }, { "name": "CZK", "description": "Czech koruna" }, { "name": "DJF", "description": "Djiboutian franc" }, { "name": "DKK", "description": "Danish krone" }, { "name": "DOP", "description": "Dominican peso" }, { "name": "DZD", "description": "Algerian dinar" }, { "name": "EGP", "description": "Egyptian pound" }, { "name": "ERN", "description": "Eritrean nakfa" }, { "name": "ETB", "description": "Ethiopian birr" }, { "name": "EUR", "description": "Euro" }, { "name": "FJD", "description": "Fiji dollar" }, { "name": "FKP", "description": "Falkland Islands pound" }, { "name": "GBP", "description": "Pound sterling" }, { "name": "GEL", "description": "Georgian lari" }, { "name": "GHS", "description": "Ghanaian cedi" }, { "name": "GIP", "description": "Gibraltar pound" }, { "name": "GMD", "description": "Gambian dalasi" }, { "name": "GNF", "description": "Guinean franc" }, { "name": "GTQ", "description": "Guatemalan quetzal" }, { "name": "GYD", "description": "Guyanese dollar" }, { "name": "HKD", "description": "Hong Kong dollar" }, { "name": "HNL", "description": "Honduran lempira" }, { "name": "HRK", "description": "Croatian kuna" }, { "name": "HTG", "description": "Haitian gourde" }, { "name": "HUF", "description": "Hungarian forint" }, { "name": "IDR", "description": "Indonesian rupiah" }, { "name": "ILS", "description": "Israeli new shekel" }, { "name": "INR", "description": "Indian rupee" }, { "name": "IQD", "description": "Iraqi dinar" }, { "name": "IRR", "description": "Iranian rial" }, { "name": "ISK", "description": "Icelandic króna" }, { "name": "JMD", "description": "Jamaican dollar" }, { "name": "JOD", "description": "Jordanian dinar" }, { "name": "JPY", "description": "Japanese yen" }, { "name": "KES", "description": "Kenyan shilling" }, { "name": "KGS", "description": "Kyrgyzstani som" }, { "name": "KHR", "description": "Cambodian riel" }, { "name": "KMF", "description": "Comoro franc" }, { "name": "KPW", "description": "North Korean won" }, { "name": "KRW", "description": "South Korean won" }, { "name": "KWD", "description": "Kuwaiti dinar" }, { "name": "KYD", "description": "Cayman Islands dollar" }, { "name": "KZT", "description": "Kazakhstani tenge" }, { "name": "LAK", "description": "Lao kip" }, { "name": "LBP", "description": "Lebanese pound" }, { "name": "LKR", "description": "Sri Lankan rupee" }, { "name": "LRD", "description": "Liberian dollar" }, { "name": "LSL", "description": "Lesotho loti" }, { "name": "LTL", "description": "Lithuanian litas" }, { "name": "LVL", "description": "Latvian lats" }, { "name": "LYD", "description": "Libyan dinar" }, { "name": "MAD", "description": "Moroccan dirham" }, { "name": "MDL", "description": "Moldovan leu" }, { "name": "MGA", "description": "Malagasy ariary" }, { "name": "MKD", "description": "Macedonian denar" }, { "name": "MMK", "description": "Myanmar kyat" }, { "name": "MNT", "description": "Mongolian tögrög" }, { "name": "MOP", "description": "Macanese pataca" }, { "name": "MRO", "description": "Mauritanian ouguiya" }, { "name": "MUR", "description": "Mauritian rupee" }, { "name": "MVR", "description": "Maldivian rufiyaa" }, { "name": "MWK", "description": "Malawian kwacha" }, { "name": "MXN", "description": "Mexican peso" }, { "name": "MXV", "description": "Mexican Unidad de Inversion" }, { "name": "MYR", "description": "Malaysian ringgit" }, { "name": "MZN", "description": "Mozambican metical" }, { "name": "NAD", "description": "Namibian dollar" }, { "name": "NGN", "description": "Nigerian naira" }, { "name": "NIO", "description": "Nicaraguan córdoba" }, { "name": "NOK", "description": "Norwegian krone" }, { "name": "NPR", "description": "Nepalese rupee" }, { "name": "NZD", "description": "New Zealand dollar" }, { "name": "OMR", "description": "Omani rial" }, { "name": "PAB", "description": "Panamanian balboa" }, { "name": "PEN", "description": "Peruvian sol" }, { "name": "PGK", "description": "Papua New Guinean kina" }, { "name": "PHP", "description": "Philippine peso" }, { "name": "PKR", "description": "Pakistani rupee" }, { "name": "PLN", "description": "Polish zBoty" }, { "name": "PYG", "description": "Paraguayan guaraní" }, { "name": "QAR", "description": "Qatari riyal" }, { "name": "RON", "description": "Romanian leu" }, { "name": "RSD", "description": "Serbian dinar" }, { "name": "RUB", "description": "Russian ruble" }, { "name": "RWF", "description": "Rwandan franc" }, { "name": "SAR", "description": "Saudi riyal" }, { "name": "SBD", "description": "Solomon Islands dollar" }, { "name": "SCR", "description": "Seychelles rupee" }, { "name": "SDG", "description": "Sudanese pound" }, { "name": "SEK", "description": "Swedish krona" }, { "name": "SGD", "description": "Singapore dollar" }, { "name": "SHP", "description": "Saint Helena pound" }, { "name": "SLL", "description": "Sierra Leonean first leone" }, { "name": "SLE", "description": "Sierra Leonean second leone" }, { "name": "SOS", "description": "Somali shilling" }, { "name": "SRD", "description": "Surinamese dollar" }, { "name": "SSP", "description": "South Sudanese pound" }, { "name": "STD", "description": "São Tomé and Príncipe dobra" }, { "name": "SVC", "description": "Salvadoran colón" }, { "name": "SYP", "description": "Syrian pound" }, { "name": "SZL", "description": "Swazi lilangeni" }, { "name": "THB", "description": "Thai baht" }, { "name": "TJS", "description": "Tajikstani somoni" }, { "name": "TMT", "description": "Turkmenistan manat" }, { "name": "TND", "description": "Tunisian dinar" }, { "name": "TOP", "description": "Tongan pa'anga" }, { "name": "TRY", "description": "Turkish lira" }, { "name": "TTD", "description": "Trinidad and Tobago dollar" }, { "name": "TWD", "description": "New Taiwan dollar" }, { "name": "TZS", "description": "Tanzanian shilling" }, { "name": "UAH", "description": "Ukrainian hryvnia" }, { "name": "UGX", "description": "Ugandan shilling" }, { "name": "USD", "description": "United States dollar" }, { "name": "USN", "description": "United States dollar (next day)" }, { "name": "USS", "description": "United States dollar (same day)" }, { "name": "UYI", "description": "Uruguay Peso en Unidedades Indexadas" }, { "name": "UYU", "description": "Uruguyan peso" }, { "name": "UZS", "description": "Uzbekistan som" }, { "name": "VEF", "description": "Venezuelan bolívar soberano" }, { "name": "VND", "description": "Vietnamese ’Óng" }, { "name": "VUV", "description": "Vanuatu vatu" }, { "name": "WST", "description": "Samoan tala" }, { "name": "XAF", "description": "CFA franc BEAC" }, { "name": "XAG", "description": "Silver" }, { "name": "XAU", "description": "Gold" }, { "name": "XBA", "description": "European Composite Unit" }, { "name": "XBB", "description": "European Monetary Unit" }, { "name": "XBC", "description": "European Unit of Account 9" }, { "name": "XBD", "description": "European Unit of Account 17" }, { "name": "XCD", "description": "East Caribbean dollar" }, { "name": "XDR", "description": "Special drawing rights (International Monetary Fund)" }, { "name": "XOF", "description": "CFA franc BCEAO" }, { "name": "XPD", "description": "Palladium" }, { "name": "XPF", "description": "CFP franc" }, { "name": "XPT", "description": "Platinum" }, { "name": "XTS", "description": "Code reserved for testing" }, { "name": "XXX", "description": "No currency" }, { "name": "YER", "description": "Yemeni rial" }, { "name": "ZAR", "description": "South African rand" }, { "name": "ZMK", "description": "Zambian kwacha" }, { "name": "ZMW", "description": "Zambian kwacha" }, { "name": "BTC", "description": "Bitcoin" }, { "name": "XUS", "description": "USD Coin" } ], "description": "Indicates the associated currency for an amount of money. Values correspond\nto [ISO 4217](https://wikipedia.org/wiki/ISO_4217).", "x-release-status": "PUBLIC" }, "DayOfWeek": { "type": "string", "enum": [ "SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT" ], "x-enum-elements": [ { "name": "SUN", "description": "Sunday" }, { "name": "MON", "description": "Monday" }, { "name": "TUE", "description": "Tuesday" }, { "name": "WED", "description": "Wednesday" }, { "name": "THU", "description": "Thursday" }, { "name": "FRI", "description": "Friday" }, { "name": "SAT", "description": "Saturday" } ], "description": "Indicates the specific day of the week.", "x-release-status": "PUBLIC" }, "Error": { "type": "object", "description": "Represents an error encountered during a request to the Connect API.\n\nSee [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) for more information.", "x-release-status": "PUBLIC", "required": [ "category", "code" ], "properties": { "category": { "$ref": "#/$defs/ErrorCategory", "description": "The high-level category for the error.\nSee [ErrorCategory](#type-errorcategory) for possible values" }, "code": { "$ref": "#/$defs/ErrorCode", "description": "The specific code of the error.\nSee [ErrorCode](#type-errorcode) for possible values" }, "detail": { "type": "string", "description": "A human-readable description of the error for debugging purposes." }, "field": { "type": "string", "description": "The name of the field provided in the original request (if any) that\nthe error pertains to." } } }, "ErrorCategory": { "type": "string", "enum": [ "API_ERROR", "AUTHENTICATION_ERROR", "INVALID_REQUEST_ERROR", "RATE_LIMIT_ERROR", "PAYMENT_METHOD_ERROR", "REFUND_ERROR", "MERCHANT_SUBSCRIPTION_ERROR", "EXTERNAL_VENDOR_ERROR" ], "x-enum-elements": [ { "name": "API_ERROR", "description": "An error occurred with the Connect API itself." }, { "name": "AUTHENTICATION_ERROR", "description": "An authentication error occurred. Most commonly, the request had\na missing, malformed, or otherwise invalid `Authorization` header." }, { "name": "INVALID_REQUEST_ERROR", "description": "The request was invalid. Most commonly, a required parameter was\nmissing, or a provided parameter had an invalid value." }, { "name": "RATE_LIMIT_ERROR", "description": "Your application reached the Square API rate limit. You might receive this error if your application sends a high number of requests\nto Square APIs in a short period of time.\n\nYour application should monitor responses for `429 RATE_LIMITED` errors and use a retry mechanism with an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff)\nschedule to resend the requests at an increasingly slower rate. It is also a good practice to use a randomized delay (jitter) in your retry schedule." }, { "name": "PAYMENT_METHOD_ERROR", "description": "An error occurred while processing a payment method. Most commonly,\nthe details of the payment method were invalid (such as a card's CVV\nor expiration date)." }, { "name": "REFUND_ERROR", "description": "An error occurred while attempting to process a refund." }, { "name": "MERCHANT_SUBSCRIPTION_ERROR", "description": "An error occurred when checking a merchant subscription status" }, { "name": "EXTERNAL_VENDOR_ERROR", "description": "An error that is returned from an external vendor's API" } ], "description": "Indicates which high-level category of error has occurred during a\nrequest to the Connect API.", "x-release-status": "PUBLIC" }, "ErrorCode": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR", "UNAUTHORIZED", "ACCESS_TOKEN_EXPIRED", "ACCESS_TOKEN_REVOKED", "CLIENT_DISABLED", "FORBIDDEN", "INSUFFICIENT_SCOPES", "APPLICATION_DISABLED", "V1_APPLICATION", "V1_ACCESS_TOKEN", "CARD_PROCESSING_NOT_ENABLED", "MERCHANT_SUBSCRIPTION_NOT_FOUND", "BAD_REQUEST", "MISSING_REQUIRED_PARAMETER", "INCORRECT_TYPE", "INVALID_TIME", "INVALID_TIME_RANGE", "INVALID_VALUE", "INVALID_CURSOR", "UNKNOWN_QUERY_PARAMETER", "CONFLICTING_PARAMETERS", "EXPECTED_JSON_BODY", "INVALID_SORT_ORDER", "VALUE_REGEX_MISMATCH", "VALUE_TOO_SHORT", "VALUE_TOO_LONG", "VALUE_TOO_LOW", "VALUE_TOO_HIGH", "VALUE_EMPTY", "ARRAY_LENGTH_TOO_LONG", "ARRAY_LENGTH_TOO_SHORT", "ARRAY_EMPTY", "EXPECTED_BOOLEAN", "EXPECTED_INTEGER", "EXPECTED_FLOAT", "EXPECTED_STRING", "EXPECTED_OBJECT", "EXPECTED_ARRAY", "EXPECTED_MAP", "EXPECTED_BASE64_ENCODED_BYTE_ARRAY", "INVALID_ARRAY_VALUE", "INVALID_ENUM_VALUE", "INVALID_CONTENT_TYPE", "INVALID_FORM_VALUE", "CUSTOMER_NOT_FOUND", "ONE_INSTRUMENT_EXPECTED", "NO_FIELDS_SET", "TOO_MANY_MAP_ENTRIES", "MAP_KEY_LENGTH_TOO_SHORT", "MAP_KEY_LENGTH_TOO_LONG", "CUSTOMER_MISSING_NAME", "CUSTOMER_MISSING_EMAIL", "INVALID_PAUSE_LENGTH", "INVALID_DATE", "UNSUPPORTED_COUNTRY", "UNSUPPORTED_CURRENCY", "APPLE_TTP_PIN_TOKEN", "CARD_EXPIRED", "INVALID_EXPIRATION", "INVALID_EXPIRATION_YEAR", "INVALID_EXPIRATION_DATE", "UNSUPPORTED_CARD_BRAND", "UNSUPPORTED_ENTRY_METHOD", "INVALID_ENCRYPTED_CARD", "INVALID_CARD", "PAYMENT_AMOUNT_MISMATCH", "GENERIC_DECLINE", "CVV_FAILURE", "ADDRESS_VERIFICATION_FAILURE", "INVALID_ACCOUNT", "CURRENCY_MISMATCH", "INSUFFICIENT_FUNDS", "INSUFFICIENT_PERMISSIONS", "CARDHOLDER_INSUFFICIENT_PERMISSIONS", "INVALID_LOCATION", "TRANSACTION_LIMIT", "VOICE_FAILURE", "PAN_FAILURE", "EXPIRATION_FAILURE", "CARD_NOT_SUPPORTED", "INVALID_PIN", "MISSING_PIN", "MISSING_ACCOUNT_TYPE", "INVALID_POSTAL_CODE", "INVALID_FEES", "MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED", "PAYMENT_LIMIT_EXCEEDED", "GIFT_CARD_AVAILABLE_AMOUNT", "ACCOUNT_UNUSABLE", "BUYER_REFUSED_PAYMENT", "DELAYED_TRANSACTION_EXPIRED", "DELAYED_TRANSACTION_CANCELED", "DELAYED_TRANSACTION_CAPTURED", "DELAYED_TRANSACTION_FAILED", "CARD_TOKEN_EXPIRED", "CARD_TOKEN_USED", "AMOUNT_TOO_HIGH", "UNSUPPORTED_INSTRUMENT_TYPE", "REFUND_AMOUNT_INVALID", "REFUND_ALREADY_PENDING", "PAYMENT_NOT_REFUNDABLE", "PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE", "REFUND_DECLINED", "INSUFFICIENT_PERMISSIONS_FOR_REFUND", "INVALID_CARD_DATA", "SOURCE_USED", "SOURCE_EXPIRED", "UNSUPPORTED_LOYALTY_REWARD_TIER", "LOCATION_MISMATCH", "IDEMPOTENCY_KEY_REUSED", "UNEXPECTED_VALUE", "SANDBOX_NOT_SUPPORTED", "INVALID_EMAIL_ADDRESS", "INVALID_PHONE_NUMBER", "CHECKOUT_EXPIRED", "BAD_CERTIFICATE", "INVALID_SQUARE_VERSION_FORMAT", "API_VERSION_INCOMPATIBLE", "CARD_PRESENCE_REQUIRED", "UNSUPPORTED_SOURCE_TYPE", "CARD_MISMATCH", "PLAID_ERROR", "PLAID_ERROR_ITEM_LOGIN_REQUIRED", "PLAID_ERROR_RATE_LIMIT", "CARD_DECLINED", "VERIFY_CVV_FAILURE", "VERIFY_AVS_FAILURE", "CARD_DECLINED_CALL_ISSUER", "CARD_DECLINED_VERIFICATION_REQUIRED", "BAD_EXPIRATION", "CHIP_INSERTION_REQUIRED", "ALLOWABLE_PIN_TRIES_EXCEEDED", "RESERVATION_DECLINED", "UNKNOWN_BODY_PARAMETER", "NOT_FOUND", "APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND", "METHOD_NOT_ALLOWED", "NOT_ACCEPTABLE", "REQUEST_TIMEOUT", "CONFLICT", "GONE", "REQUEST_ENTITY_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "UNPROCESSABLE_ENTITY", "RATE_LIMITED", "NOT_IMPLEMENTED", "BAD_GATEWAY", "SERVICE_UNAVAILABLE", "TEMPORARY_ERROR", "GATEWAY_TIMEOUT" ], "x-enum-elements": [ { "name": "INTERNAL_SERVER_ERROR", "description": "A general server error occurred.", "error-category": "API_ERROR" }, { "name": "UNAUTHORIZED", "description": "A general authorization error occurred.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "ACCESS_TOKEN_EXPIRED", "description": "The provided access token has expired.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "ACCESS_TOKEN_REVOKED", "description": "The provided access token has been revoked.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "CLIENT_DISABLED", "description": "The provided client has been disabled.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "FORBIDDEN", "description": "A general access error occurred.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "INSUFFICIENT_SCOPES", "description": "The provided access token does not have permission\nto execute the requested action.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "APPLICATION_DISABLED", "description": "The calling application was disabled.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "V1_APPLICATION", "description": "The calling application was created prior to\n2016-03-30 and is not compatible with v2 Square API calls.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "V1_ACCESS_TOKEN", "description": "The calling application is using an access token\ncreated prior to 2016-03-30 and is not compatible with v2 Square API\ncalls.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CARD_PROCESSING_NOT_ENABLED", "description": "The location provided in the API call is not\nenabled for credit card processing.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "MERCHANT_SUBSCRIPTION_NOT_FOUND", "description": "A required subscription was not found for the merchant", "error-category": "MERCHANT_SUBSCRIPTION_ERROR" }, { "name": "BAD_REQUEST", "description": "A general error occurred with the request.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "MISSING_REQUIRED_PARAMETER", "description": "The request is missing a required path, query, or\nbody parameter.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INCORRECT_TYPE", "description": "The value provided in the request is the wrong\ntype. For example, a string instead of an integer.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_TIME", "description": "Formatting for the provided time value is\nincorrect.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_TIME_RANGE", "description": "The time range provided in the request is invalid.\nFor example, the end time is before the start time.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_VALUE", "description": "The provided value is invalid. For example,\nincluding `%` in a phone number.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_CURSOR", "description": "The pagination cursor included in the request is\ninvalid.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNKNOWN_QUERY_PARAMETER", "description": "The query parameters provided is invalid for the\nrequested endpoint.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CONFLICTING_PARAMETERS", "description": "One or more of the request parameters conflict with\neach other.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_JSON_BODY", "description": "The request body is not a JSON object.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_SORT_ORDER", "description": "The provided sort order is not a valid key.\nCurrently, sort order must be `ASC` or `DESC`.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_REGEX_MISMATCH", "description": "The provided value does not match an expected\nregular expression.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_TOO_SHORT", "description": "The provided string value is shorter than the\nminimum length allowed.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_TOO_LONG", "description": "The provided string value is longer than the\nmaximum length allowed.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_TOO_LOW", "description": "The provided value is less than the supported\nminimum.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_TOO_HIGH", "description": "The provided value is greater than the supported\nmaximum.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_EMPTY", "description": "The provided value has a default (empty) value\nsuch as a blank string.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "ARRAY_LENGTH_TOO_LONG", "description": "The provided array has too many elements.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "ARRAY_LENGTH_TOO_SHORT", "description": "The provided array has too few elements.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "ARRAY_EMPTY", "description": "The provided array is empty.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_BOOLEAN", "description": "The endpoint expected the provided value to be a\nboolean.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_INTEGER", "description": "The endpoint expected the provided value to be an\ninteger.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_FLOAT", "description": "The endpoint expected the provided value to be a\nfloat.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_STRING", "description": "The endpoint expected the provided value to be a\nstring.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_OBJECT", "description": "The endpoint expected the provided value to be a\nJSON object.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_ARRAY", "description": "The endpoint expected the provided value to be an\narray or list.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_MAP", "description": "The endpoint expected the provided value to be a\nmap or associative array.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_BASE64_ENCODED_BYTE_ARRAY", "description": "The endpoint expected the provided value to be an\narray encoded in base64.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_ARRAY_VALUE", "description": "One or more objects in the array does not match the\narray type.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_ENUM_VALUE", "description": "The provided static string is not valid for the\nfield.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_CONTENT_TYPE", "description": "Invalid content type header.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_FORM_VALUE", "description": "Only relevant for applications created prior to\n2016-03-30. Indicates there was an error while parsing form values.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CUSTOMER_NOT_FOUND", "description": "The provided customer id can't be found in the merchant's customers list.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "ONE_INSTRUMENT_EXPECTED", "description": "A general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "NO_FIELDS_SET", "description": "A general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "TOO_MANY_MAP_ENTRIES", "description": "Too many entries in the map field.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "MAP_KEY_LENGTH_TOO_SHORT", "description": "The length of one of the provided keys in the map is too short.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "MAP_KEY_LENGTH_TOO_LONG", "description": "The length of one of the provided keys in the map is too long.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CUSTOMER_MISSING_NAME", "description": "The provided customer does not have a recorded name.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CUSTOMER_MISSING_EMAIL", "description": "The provided customer does not have a recorded email.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_PAUSE_LENGTH", "description": "The subscription cannot be paused longer than the duration of the current phase.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_DATE", "description": "The subscription cannot be paused/resumed on the given date.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_COUNTRY", "description": "The API request references an unsupported country.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_CURRENCY", "description": "The API request references an unsupported currency.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "APPLE_TTP_PIN_TOKEN", "description": "The payment was declined by the card issuer during an Apple Tap to Pay (TTP)\ntransaction with a request for the card's PIN. This code will be returned alongside\n`CARD_DECLINED_VERIFICATION_REQUIRED` as a supplemental error, and will include an\nissuer-provided token in the `details` field that is needed to initiate the PIN\ncollection flow on the iOS device.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CARD_EXPIRED", "description": "The card issuer declined the request because the card is expired.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_EXPIRATION", "description": "The expiration date for the payment card is invalid. For example,\nit indicates a date in the past.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_EXPIRATION_YEAR", "description": "The expiration year for the payment card is invalid. For example,\nit indicates a year in the past or contains invalid characters.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_EXPIRATION_DATE", "description": "The expiration date for the payment card is invalid. For example,\nit contains invalid characters.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_CARD_BRAND", "description": "The credit card provided is not from a supported issuer.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "UNSUPPORTED_ENTRY_METHOD", "description": "The entry method for the credit card (swipe, dip, tap) is not supported.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_ENCRYPTED_CARD", "description": "The encrypted card information is invalid.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_CARD", "description": "The credit card cannot be validated based on the provided details.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "PAYMENT_AMOUNT_MISMATCH", "description": "The payment was declined because there was a payment amount mismatch.\nThe money amount Square was expecting does not match the amount provided.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "GENERIC_DECLINE", "description": "Square received a decline without any additional information.\nIf the payment information seems correct, the buyer can contact their\nissuer to ask for more information.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CVV_FAILURE", "description": "The card issuer declined the request because the CVV value is invalid.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "ADDRESS_VERIFICATION_FAILURE", "description": "The card issuer declined the request because the postal code is invalid.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_ACCOUNT", "description": "The issuer was not able to locate the account on record.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CURRENCY_MISMATCH", "description": "The currency associated with the payment is not valid for the provided\nfunding source. For example, a gift card funded in USD cannot be used to process\npayments in GBP.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INSUFFICIENT_FUNDS", "description": "The funding source has insufficient funds to cover the payment.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INSUFFICIENT_PERMISSIONS", "description": "The Square account does not have the permissions to accept\nthis payment. For example, Square may limit which merchants are\nallowed to receive gift card payments.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CARDHOLDER_INSUFFICIENT_PERMISSIONS", "description": "The card issuer has declined the transaction due to restrictions on where the card can be used.\nFor example, a gift card is limited to a single merchant.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_LOCATION", "description": "The Square account cannot take payments in the specified region.\nA Square account can take payments only from the region where the account was created.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "TRANSACTION_LIMIT", "description": "The card issuer has determined the payment amount is either too high or too low.\nThe API returns the error code mostly for credit cards (for example, the card reached\nthe credit limit). However, sometimes the issuer bank can indicate the error for debit\nor prepaid cards (for example, card has insufficient funds).", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "VOICE_FAILURE", "description": "The card issuer declined the request because the issuer requires voice authorization from the cardholder. The seller should ask the customer to contact the card issuing bank to authorize the payment.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "PAN_FAILURE", "description": "The specified card number is invalid. For example, it is of\nincorrect length or is incorrectly formatted.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "EXPIRATION_FAILURE", "description": "The card expiration date is either invalid or indicates that the\ncard is expired.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CARD_NOT_SUPPORTED", "description": "The card is not supported either in the geographic region or by\nthe [merchant category code](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code) (MCC).", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_PIN", "description": "The card issuer declined the request because the PIN is invalid.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "MISSING_PIN", "description": "The payment is missing a required PIN.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "MISSING_ACCOUNT_TYPE", "description": "The payment is missing a required ACCOUNT_TYPE parameter.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_POSTAL_CODE", "description": "The postal code is incorrectly formatted.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_FEES", "description": "The app_fee_money on a payment is too high.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED", "description": "The card must be swiped, tapped, or dipped. Payments attempted by manually entering the card number are declined.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "PAYMENT_LIMIT_EXCEEDED", "description": "Square declined the request because the payment amount exceeded the processing limit for this merchant.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "GIFT_CARD_AVAILABLE_AMOUNT", "description": "When a Gift Card is a payment source, you can allow taking a partial payment\nby adding the `accept_partial_authorization` parameter in the request.\nHowever, taking such a partial payment does not work if your request also includes\n`tip_money`, `app_fee_money`, or both. Square declines such payments and returns\nthe `GIFT_CARD_AVAILABLE_AMOUNT` error.\nFor more information, see\n[CreatePayment errors (additional information)](https://developer.squareup.com/docs/payments-api/error-codes#createpayment-errors-additional-information).", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "ACCOUNT_UNUSABLE", "description": "The account provided cannot carry out transactions.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "BUYER_REFUSED_PAYMENT", "description": "Bank account rejected or was not authorized for the payment.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "DELAYED_TRANSACTION_EXPIRED", "description": "The application tried to update a delayed-capture payment that has expired.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "DELAYED_TRANSACTION_CANCELED", "description": "The application tried to cancel a delayed-capture payment that was already cancelled.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "DELAYED_TRANSACTION_CAPTURED", "description": "The application tried to capture a delayed-capture payment that was already captured.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "DELAYED_TRANSACTION_FAILED", "description": "The application tried to update a delayed-capture payment that failed.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CARD_TOKEN_EXPIRED", "description": "The provided card token (nonce) has expired.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CARD_TOKEN_USED", "description": "The provided card token (nonce) was already used to process the payment or refund.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "AMOUNT_TOO_HIGH", "description": "The requested payment amount is too high for the provided payment source.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_INSTRUMENT_TYPE", "description": "The API request references an unsupported instrument type.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "REFUND_AMOUNT_INVALID", "description": "The requested refund amount exceeds the amount available to refund.", "error-category": "REFUND_ERROR" }, { "name": "REFUND_ALREADY_PENDING", "description": "The payment already has a pending refund.", "error-category": "REFUND_ERROR" }, { "name": "PAYMENT_NOT_REFUNDABLE", "description": "The payment is not refundable. For example, the payment is too old to be refunded.", "error-category": "REFUND_ERROR" }, { "name": "PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE", "description": "The payment is not refundable because it has been disputed.", "error-category": "REFUND_ERROR" }, { "name": "REFUND_DECLINED", "description": "Request failed - The card issuer declined the refund.", "error-category": "REFUND_ERROR" }, { "name": "INSUFFICIENT_PERMISSIONS_FOR_REFUND", "description": "The Square account does not have the permissions to process this refund.", "error-category": "REFUND_ERROR" }, { "name": "INVALID_CARD_DATA", "description": "Generic error - the provided card data is invalid.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "SOURCE_USED", "description": "The provided source id was already used to create a card.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "SOURCE_EXPIRED", "description": "The provided source id has expired.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_LOYALTY_REWARD_TIER", "description": "The referenced loyalty program reward tier is not supported.\nThis could happen if the reward tier created in a first party\napplication is incompatible with the Loyalty API.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "LOCATION_MISMATCH", "description": "Generic error - the given location does not matching what is expected.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "IDEMPOTENCY_KEY_REUSED", "description": "The provided idempotency key has already been used.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNEXPECTED_VALUE", "description": "General error - the value provided was unexpected.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "SANDBOX_NOT_SUPPORTED", "description": "The API request is not supported in sandbox.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_EMAIL_ADDRESS", "description": "The provided email address is invalid.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_PHONE_NUMBER", "description": "The provided phone number is invalid.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CHECKOUT_EXPIRED", "description": "The provided checkout URL has expired.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "BAD_CERTIFICATE", "description": "Bad certificate.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_SQUARE_VERSION_FORMAT", "description": "The provided Square-Version is incorrectly formatted.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "API_VERSION_INCOMPATIBLE", "description": "The provided Square-Version is incompatible with the requested action.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CARD_PRESENCE_REQUIRED", "description": "The transaction requires that a card be present.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_SOURCE_TYPE", "description": "The API request references an unsupported source type.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CARD_MISMATCH", "description": "The provided card does not match what is expected.", "error-category": "REFUND_ERROR" }, { "name": "PLAID_ERROR", "description": "Generic plaid error", "error-category": "EXTERNAL_VENDOR_ERROR" }, { "name": "PLAID_ERROR_ITEM_LOGIN_REQUIRED", "description": "Plaid error - ITEM_LOGIN_REQUIRED", "error-category": "EXTERNAL_VENDOR_ERROR" }, { "name": "PLAID_ERROR_RATE_LIMIT", "description": "Plaid error - RATE_LIMIT", "error-category": "EXTERNAL_VENDOR_ERROR" }, { "name": "CARD_DECLINED", "description": "The card was declined.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "VERIFY_CVV_FAILURE", "description": "The CVV could not be verified.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "VERIFY_AVS_FAILURE", "description": "The AVS could not be verified.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CARD_DECLINED_CALL_ISSUER", "description": "The payment card was declined with a request\nfor the card holder to call the issuer.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CARD_DECLINED_VERIFICATION_REQUIRED", "description": "The payment card was declined with a request\nfor additional verification.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "BAD_EXPIRATION", "description": "The card expiration date is either missing or\nincorrectly formatted.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CHIP_INSERTION_REQUIRED", "description": "The card issuer requires that the card be read\nusing a chip reader.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "ALLOWABLE_PIN_TRIES_EXCEEDED", "description": "The card has exhausted its available pin entry\nretries set by the card issuer. Resolving the error typically requires the\ncard holder to contact the card issuer.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "RESERVATION_DECLINED", "description": "The card issuer declined the refund.", "error-category": "REFUND_ERROR" }, { "name": "UNKNOWN_BODY_PARAMETER", "description": "The body parameter is not recognized by the requested endpoint.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "NOT_FOUND", "description": "Not Found - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND", "description": "Square could not find the associated Apple Pay certificate.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "METHOD_NOT_ALLOWED", "description": "Method Not Allowed - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "NOT_ACCEPTABLE", "description": "Not Acceptable - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "REQUEST_TIMEOUT", "description": "Request Timeout - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CONFLICT", "description": "Conflict - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "GONE", "description": "The target resource is no longer available and this\ncondition is likely to be permanent.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "REQUEST_ENTITY_TOO_LARGE", "description": "Request Entity Too Large - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_MEDIA_TYPE", "description": "Unsupported Media Type - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNPROCESSABLE_ENTITY", "description": "Unprocessable Entity - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "RATE_LIMITED", "description": "Rate Limited - a general error occurred.", "error-category": "RATE_LIMIT_ERROR" }, { "name": "NOT_IMPLEMENTED", "description": "Not Implemented - a general error occurred.", "error-category": "API_ERROR" }, { "name": "BAD_GATEWAY", "description": "Bad Gateway - a general error occurred.", "error-category": "API_ERROR" }, { "name": "SERVICE_UNAVAILABLE", "description": "Service Unavailable - a general error occurred.", "error-category": "API_ERROR" }, { "name": "TEMPORARY_ERROR", "description": "A temporary internal error occurred. You can safely retry your call\nusing the same idempotency key.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "GATEWAY_TIMEOUT", "description": "Gateway Timeout - a general error occurred.", "error-category": "API_ERROR" } ], "description": "Indicates the specific error that occurred during a request to a\nSquare API.", "x-release-status": "PUBLIC" }, "ExcludeStrategy": { "type": "string", "enum": [ "LEAST_EXPENSIVE", "MOST_EXPENSIVE" ], "x-enum-elements": [ { "name": "LEAST_EXPENSIVE", "description": "The least expensive matched products are excluded from the pricing. If\nthe pricing rule is set to exclude one product and multiple products in the\nmatch set qualify as least expensive, then one will be excluded at random.\n\nExcluding the least expensive product gives the best discount value to the buyer." }, { "name": "MOST_EXPENSIVE", "description": "The most expensive matched product is excluded from the pricing rule.\nIf multiple products have the same price and all qualify as least expensive,\none will be excluded at random.\n\nThis guarantees that the most expensive product is purchased at full price." } ], "description": "Indicates which products matched by a CatalogPricingRule\nwill be excluded if the pricing rule uses an exclude set.", "x-release-status": "BETA" }, "InventoryAlertType": { "type": "string", "enum": [ "NONE", "LOW_QUANTITY" ], "x-enum-elements": [ { "name": "NONE", "description": "The variation does not display an alert." }, { "name": "LOW_QUANTITY", "description": "The variation generates an alert when its quantity is low." } ], "description": "Indicates whether Square should alert the merchant when the inventory quantity of a CatalogItemVariation is low.", "x-release-status": "PUBLIC" }, "ItemVariationLocationOverrides": { "type": "object", "description": "Price and inventory alerting overrides for a `CatalogItemVariation` at a specific `Location`.", "x-release-status": "PUBLIC", "properties": { "location_id": { "type": [ "string", "null" ], "description": "The ID of the `Location`. This can include locations that are deactivated." }, "price_money": { "$ref": "#/$defs/Money", "description": "The price of the `CatalogItemVariation` at the given `Location`, or blank for variable pricing." }, "pricing_type": { "$ref": "#/$defs/CatalogPricingType", "description": "The pricing type (fixed or variable) for the `CatalogItemVariation` at the given `Location`.\nSee [CatalogPricingType](#type-catalogpricingtype) for possible values" }, "track_inventory": { "type": [ "boolean", "null" ], "description": "If `true`, inventory tracking is active for the `CatalogItemVariation` at this `Location`." }, "inventory_alert_type": { "$ref": "#/$defs/InventoryAlertType", "description": "Indicates whether the `CatalogItemVariation` displays an alert when its inventory\nquantity is less than or equal to its `inventory_alert_threshold`.\nSee [InventoryAlertType](#type-inventoryalerttype) for possible values" }, "inventory_alert_threshold": { "type": [ "integer", "null" ], "description": "If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type`\nis `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard.\n\nThis value is always an integer.", "format": "int64" }, "sold_out": { "type": "boolean", "description": "Indicates whether the overridden item variation is sold out at the specified location.\n\nWhen inventory tracking is enabled on the item variation either globally or at the specified location,\nthe item variation is automatically marked as sold out when its inventory count reaches zero. The seller\ncan manually set the item variation as sold out even when the inventory count is greater than zero.\nAttempts by an application to set this attribute are ignored. Regardless how the sold-out status is set,\napplications should treat its inventory count as zero when this attribute value is `true`.", "readOnly": true }, "sold_out_valid_until": { "type": "string", "description": "The seller-assigned timestamp, of the RFC 3339 format, to indicate when this sold-out variation\nbecomes available again at the specified location. Attempts by an application to set this attribute are ignored.\nWhen the current time is later than this attribute value, the affected item variation is no longer sold out.", "readOnly": true } } }, "MeasurementUnit": { "type": "object", "description": "Represents a unit of measurement to use with a quantity, such as ounces\nor inches. Exactly one of the following fields are required: `custom_unit`,\n`area_unit`, `length_unit`, `volume_unit`, and `weight_unit`.", "x-release-status": "PUBLIC", "properties": { "custom_unit": { "$ref": "#/$defs/MeasurementUnitCustom", "description": "A custom unit of measurement defined by the seller using the Point of Sale\napp or ad-hoc as an order line item." }, "area_unit": { "$ref": "#/$defs/MeasurementUnitArea", "description": "Represents a standard area unit.\nSee [MeasurementUnitArea](#type-measurementunitarea) for possible values" }, "length_unit": { "$ref": "#/$defs/MeasurementUnitLength", "description": "Represents a standard length unit.\nSee [MeasurementUnitLength](#type-measurementunitlength) for possible values" }, "volume_unit": { "$ref": "#/$defs/MeasurementUnitVolume", "description": "Represents a standard volume unit.\nSee [MeasurementUnitVolume](#type-measurementunitvolume) for possible values" }, "weight_unit": { "$ref": "#/$defs/MeasurementUnitWeight", "description": "Represents a standard unit of weight or mass.\nSee [MeasurementUnitWeight](#type-measurementunitweight) for possible values" }, "generic_unit": { "$ref": "#/$defs/MeasurementUnitGeneric", "description": "Reserved for API integrations that lack the ability to specify a real measurement unit\nSee [MeasurementUnitGeneric](#type-measurementunitgeneric) for possible values" }, "time_unit": { "$ref": "#/$defs/MeasurementUnitTime", "description": "Represents a standard unit of time.\nSee [MeasurementUnitTime](#type-measurementunittime) for possible values" }, "type": { "$ref": "#/$defs/MeasurementUnitUnitType", "description": "Represents the type of the measurement unit.\nSee [MeasurementUnitUnitType](#type-measurementunitunittype) for possible values" } } }, "MeasurementUnitArea": { "type": "string", "enum": [ "IMPERIAL_ACRE", "IMPERIAL_SQUARE_INCH", "IMPERIAL_SQUARE_FOOT", "IMPERIAL_SQUARE_YARD", "IMPERIAL_SQUARE_MILE", "METRIC_SQUARE_CENTIMETER", "METRIC_SQUARE_METER", "METRIC_SQUARE_KILOMETER" ], "x-enum-elements": [ { "name": "IMPERIAL_ACRE", "description": "The area is measured in acres." }, { "name": "IMPERIAL_SQUARE_INCH", "description": "The area is measured in square inches." }, { "name": "IMPERIAL_SQUARE_FOOT", "description": "The area is measured in square feet." }, { "name": "IMPERIAL_SQUARE_YARD", "description": "The area is measured in square yards." }, { "name": "IMPERIAL_SQUARE_MILE", "description": "The area is measured in square miles." }, { "name": "METRIC_SQUARE_CENTIMETER", "description": "The area is measured in square centimeters." }, { "name": "METRIC_SQUARE_METER", "description": "The area is measured in square meters." }, { "name": "METRIC_SQUARE_KILOMETER", "description": "The area is measured in square kilometers." } ], "description": "Unit of area used to measure a quantity.", "x-release-status": "PUBLIC" }, "MeasurementUnitCustom": { "type": "object", "description": "The information needed to define a custom unit, provided by the seller.", "x-release-status": "PUBLIC", "required": [ "name", "abbreviation" ], "properties": { "name": { "type": "string", "description": "The name of the custom unit, for example \"bushel\"." }, "abbreviation": { "type": "string", "description": "The abbreviation of the custom unit, such as \"bsh\" (bushel). This appears\nin the cart for the Point of Sale app, and in reports." } } }, "MeasurementUnitGeneric": { "type": "string", "enum": [ "UNIT" ], "x-enum-elements": [ { "name": "UNIT", "description": "The generic unit." } ], "x-release-status": "PUBLIC" }, "MeasurementUnitLength": { "type": "string", "enum": [ "IMPERIAL_INCH", "IMPERIAL_FOOT", "IMPERIAL_YARD", "IMPERIAL_MILE", "METRIC_MILLIMETER", "METRIC_CENTIMETER", "METRIC_METER", "METRIC_KILOMETER" ], "x-enum-elements": [ { "name": "IMPERIAL_INCH", "description": "The length is measured in inches." }, { "name": "IMPERIAL_FOOT", "description": "The length is measured in feet." }, { "name": "IMPERIAL_YARD", "description": "The length is measured in yards." }, { "name": "IMPERIAL_MILE", "description": "The length is measured in miles." }, { "name": "METRIC_MILLIMETER", "description": "The length is measured in millimeters." }, { "name": "METRIC_CENTIMETER", "description": "The length is measured in centimeters." }, { "name": "METRIC_METER", "description": "The length is measured in meters." }, { "name": "METRIC_KILOMETER", "description": "The length is measured in kilometers." } ], "description": "The unit of length used to measure a quantity.", "x-release-status": "PUBLIC" }, "MeasurementUnitTime": { "type": "string", "enum": [ "GENERIC_MILLISECOND", "GENERIC_SECOND", "GENERIC_MINUTE", "GENERIC_HOUR", "GENERIC_DAY" ], "x-enum-elements": [ { "name": "GENERIC_MILLISECOND", "description": "The time is measured in milliseconds." }, { "name": "GENERIC_SECOND", "description": "The time is measured in seconds." }, { "name": "GENERIC_MINUTE", "description": "The time is measured in minutes." }, { "name": "GENERIC_HOUR", "description": "The time is measured in hours." }, { "name": "GENERIC_DAY", "description": "The time is measured in days." } ], "description": "Unit of time used to measure a quantity (a duration).", "x-release-status": "PUBLIC" }, "MeasurementUnitUnitType": { "type": "string", "enum": [ "TYPE_CUSTOM", "TYPE_AREA", "TYPE_LENGTH", "TYPE_VOLUME", "TYPE_WEIGHT", "TYPE_GENERIC" ], "x-enum-elements": [ { "name": "TYPE_CUSTOM", "description": "The unit details are contained in the custom_unit field." }, { "name": "TYPE_AREA", "description": "The unit details are contained in the area_unit field." }, { "name": "TYPE_LENGTH", "description": "The unit details are contained in the length_unit field." }, { "name": "TYPE_VOLUME", "description": "The unit details are contained in the volume_unit field." }, { "name": "TYPE_WEIGHT", "description": "The unit details are contained in the weight_unit field." }, { "name": "TYPE_GENERIC", "description": "The unit details are contained in the generic_unit field." } ], "description": "Describes the type of this unit and indicates which field contains the unit information. This is an ‘open’ enum.", "x-release-status": "PUBLIC" }, "MeasurementUnitVolume": { "type": "string", "enum": [ "GENERIC_FLUID_OUNCE", "GENERIC_SHOT", "GENERIC_CUP", "GENERIC_PINT", "GENERIC_QUART", "GENERIC_GALLON", "IMPERIAL_CUBIC_INCH", "IMPERIAL_CUBIC_FOOT", "IMPERIAL_CUBIC_YARD", "METRIC_MILLILITER", "METRIC_LITER" ], "x-enum-elements": [ { "name": "GENERIC_FLUID_OUNCE", "description": "The volume is measured in ounces." }, { "name": "GENERIC_SHOT", "description": "The volume is measured in shots." }, { "name": "GENERIC_CUP", "description": "The volume is measured in cups." }, { "name": "GENERIC_PINT", "description": "The volume is measured in pints." }, { "name": "GENERIC_QUART", "description": "The volume is measured in quarts." }, { "name": "GENERIC_GALLON", "description": "The volume is measured in gallons." }, { "name": "IMPERIAL_CUBIC_INCH", "description": "The volume is measured in cubic inches." }, { "name": "IMPERIAL_CUBIC_FOOT", "description": "The volume is measured in cubic feet." }, { "name": "IMPERIAL_CUBIC_YARD", "description": "The volume is measured in cubic yards." }, { "name": "METRIC_MILLILITER", "description": "The volume is measured in metric milliliters." }, { "name": "METRIC_LITER", "description": "The volume is measured in metric liters." } ], "description": "The unit of volume used to measure a quantity.", "x-release-status": "PUBLIC" }, "MeasurementUnitWeight": { "type": "string", "enum": [ "IMPERIAL_WEIGHT_OUNCE", "IMPERIAL_POUND", "IMPERIAL_STONE", "METRIC_MILLIGRAM", "METRIC_GRAM", "METRIC_KILOGRAM" ], "x-enum-elements": [ { "name": "IMPERIAL_WEIGHT_OUNCE", "description": "The weight is measured in ounces." }, { "name": "IMPERIAL_POUND", "description": "The weight is measured in pounds." }, { "name": "IMPERIAL_STONE", "description": "The weight is measured in stones." }, { "name": "METRIC_MILLIGRAM", "description": "The weight is measured in milligrams." }, { "name": "METRIC_GRAM", "description": "The weight is measured in grams." }, { "name": "METRIC_KILOGRAM", "description": "The weight is measured in kilograms." } ], "description": "Unit of weight used to measure a quantity.", "x-release-status": "PUBLIC" }, "ModifierLocationOverrides": { "type": "object", "description": "Location-specific overrides for specified properties of a `CatalogModifier` object.", "x-release-status": "PUBLIC", "properties": { "location_id": { "type": [ "string", "null" ], "description": "The ID of the `Location` object representing the location. This can include a deactivated location." }, "price_money": { "$ref": "#/$defs/Money", "description": "The overridden price at the specified location. If this is unspecified, the modifier price is not overridden.\nThe modifier becomes free of charge at the specified location, when this `price_money` field is set to 0." }, "sold_out": { "type": "boolean", "description": "Indicates whether the modifier is sold out at the specified location or not. As an example, for cheese (modifier) burger (item), when the modifier is sold out, it is the cheese, but not the burger, that is sold out.\nThe seller can manually set this sold out status. Attempts by an application to set this attribute are ignored.", "readOnly": true } } }, "Money": { "type": "object", "description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.", "x-release-status": "PUBLIC", "properties": { "amount": { "type": [ "integer", "null" ], "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "format": "int64" }, "currency": { "$ref": "#/$defs/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](entity:Currency) for possible values.\nSee [Currency](#type-currency) for possible values" } } }, "Product": { "type": "string", "enum": [ "SQUARE_POS", "EXTERNAL_API", "BILLING", "APPOINTMENTS", "INVOICES", "ONLINE_STORE", "PAYROLL", "DASHBOARD", "ITEM_LIBRARY_IMPORT", "OTHER" ], "x-enum-elements": [ { "name": "SQUARE_POS", "description": "Square Point of Sale application." }, { "name": "EXTERNAL_API", "description": "Square Connect APIs (for example, Orders API or Checkout API)." }, { "name": "BILLING", "description": "A Square subscription (various products)." }, { "name": "APPOINTMENTS", "description": "Square Appointments." }, { "name": "INVOICES", "description": "Square Invoices." }, { "name": "ONLINE_STORE", "description": "Square Online Store." }, { "name": "PAYROLL", "description": "Square Payroll." }, { "name": "DASHBOARD", "description": "Square Dashboard." }, { "name": "ITEM_LIBRARY_IMPORT", "description": "Item Library Import." }, { "name": "OTHER", "description": "A Square product that does not match any other value." } ], "description": "Indicates the Square product used to generate a change.", "x-release-status": "PUBLIC" }, "SourceApplication": { "type": "object", "description": "Represents information about the application used to generate a change.", "x-release-status": "PUBLIC", "properties": { "product": { "$ref": "#/$defs/Product", "description": "__Read only__ The [product](entity:Product) type of the application.\nSee [Product](#type-product) for possible values" }, "application_id": { "type": [ "string", "null" ], "description": "__Read only__ The Square-assigned ID of the application. This field is used only if the\n[product](entity:Product) type is `EXTERNAL_API`." }, "name": { "type": [ "string", "null" ], "description": "__Read only__ The display name of the application\n(for example, `\"Custom Application\"` or `\"Square POS 4.74 for Android\"`)." } } }, "SubscriptionCadence": { "type": "string", "enum": [ "DAILY", "WEEKLY", "EVERY_TWO_WEEKS", "THIRTY_DAYS", "SIXTY_DAYS", "NINETY_DAYS", "MONTHLY", "EVERY_TWO_MONTHS", "QUARTERLY", "EVERY_FOUR_MONTHS", "EVERY_SIX_MONTHS", "ANNUAL", "EVERY_TWO_YEARS" ], "x-enum-elements": [ { "name": "DAILY", "description": "Once per day" }, { "name": "WEEKLY", "description": "Once per week" }, { "name": "EVERY_TWO_WEEKS", "description": "Every two weeks" }, { "name": "THIRTY_DAYS", "description": "Once every 30 days" }, { "name": "SIXTY_DAYS", "description": "Once every 60 days" }, { "name": "NINETY_DAYS", "description": "Once every 90 days" }, { "name": "MONTHLY", "description": "Once per month" }, { "name": "EVERY_TWO_MONTHS", "description": "Once every two months" }, { "name": "QUARTERLY", "description": "Once every three months" }, { "name": "EVERY_FOUR_MONTHS", "description": "Once every four months" }, { "name": "EVERY_SIX_MONTHS", "description": "Once every six months" }, { "name": "ANNUAL", "description": "Once per year" }, { "name": "EVERY_TWO_YEARS", "description": "Once every two years" } ], "description": "Determines the billing cadence of a [Subscription](entity:Subscription)", "x-release-status": "PUBLIC" }, "SubscriptionPhase": { "type": "object", "description": "Describes a phase in a subscription plan variation. For more information, see [Subscription Plans and Variations](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations).", "x-release-status": "PUBLIC", "required": [ "cadence" ], "properties": { "uid": { "type": [ "string", "null" ], "description": "The Square-assigned ID of the subscription phase. This field cannot be changed after a `SubscriptionPhase` is created." }, "cadence": { "$ref": "#/$defs/SubscriptionCadence", "description": "The billing cadence of the phase. For example, weekly or monthly. This field cannot be changed after a `SubscriptionPhase` is created.\nSee [SubscriptionCadence](#type-subscriptioncadence) for possible values" }, "periods": { "type": [ "integer", "null" ], "description": "The number of `cadence`s the phase lasts. If not set, the phase never ends. Only the last phase can be indefinite. This field cannot be changed after a `SubscriptionPhase` is created." }, "recurring_price_money": { "$ref": "#/$defs/Money", "description": "The amount to bill for each `cadence`. Failure to specify this field results in a `MISSING_REQUIRED_PARAMETER` error at runtime." }, "ordinal": { "type": [ "integer", "null" ], "description": "The position this phase appears in the sequence of phases defined for the plan, indexed from 0. This field cannot be changed after a `SubscriptionPhase` is created.", "format": "int64" }, "pricing": { "$ref": "#/$defs/SubscriptionPricing", "description": "The subscription pricing." } } }, "SubscriptionPricing": { "type": "object", "description": "Describes the pricing for the subscription.", "x-release-status": "PUBLIC", "properties": { "type": { "$ref": "#/$defs/SubscriptionPricingType", "description": "RELATIVE or STATIC\nSee [SubscriptionPricingType](#type-subscriptionpricingtype) for possible values" }, "discount_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The ids of the discount catalog objects" }, "price_money": { "$ref": "#/$defs/Money", "description": "The price of the subscription, if STATIC" } } }, "SubscriptionPricingType": { "type": "string", "enum": [ "STATIC", "RELATIVE" ], "x-enum-elements": [ { "name": "STATIC", "description": "Static pricing" }, { "name": "RELATIVE", "description": "Relative pricing" } ], "description": "Determines the pricing of a [Subscription](entity:Subscription)", "x-release-status": "PUBLIC" }, "TaxCalculationPhase": { "type": "string", "enum": [ "TAX_SUBTOTAL_PHASE", "TAX_TOTAL_PHASE" ], "x-enum-elements": [ { "name": "TAX_SUBTOTAL_PHASE", "description": "The fee is calculated based on the payment's subtotal." }, { "name": "TAX_TOTAL_PHASE", "description": "The fee is calculated based on the payment's total." } ], "description": "When to calculate the taxes due on a cart.", "x-release-status": "PUBLIC" }, "TaxInclusionType": { "type": "string", "enum": [ "ADDITIVE", "INCLUSIVE" ], "x-enum-elements": [ { "name": "ADDITIVE", "description": "The tax is an additive tax. The tax amount is added on top of the\nCatalogItemVariation price. For example, a $1.00 item with a 10% additive\ntax would have a total cost to the buyer of $1.10." }, { "name": "INCLUSIVE", "description": "The tax is an inclusive tax. The tax amount is included in the\nCatalogItemVariation price. For example, a $1.00 item with a 10% inclusive\ntax would have a total cost to the buyer of $1.00, with $0.91 (91 cents) of\nthat total being the cost of the item and $0.09 (9 cents) being tax." } ], "description": "Whether to the tax amount should be additional to or included in the CatalogItem price.", "x-release-status": "PUBLIC" } } }