{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/square/main/json-schema/square-create-payment-link-response-schema.json", "title": "CreatePaymentLinkResponse", "x-generated": "2026-10-12", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/square-checkout-api-openapi.yml#/components/schemas/CreatePaymentLinkResponse", "type": "object", "x-release-status": "PUBLIC", "properties": { "errors": { "type": "array", "items": { "$ref": "#/$defs/Error" }, "description": "Any errors that occurred during the request." }, "payment_link": { "$ref": "#/$defs/PaymentLink", "description": "The created payment link." }, "related_resources": { "$ref": "#/$defs/PaymentLinkRelatedResources", "description": "The list of related objects." } }, "$defs": { "AcceptedPaymentMethods": { "type": "object", "x-release-status": "PUBLIC", "properties": { "apple_pay": { "type": [ "boolean", "null" ], "description": "Whether Apple Pay is accepted at checkout." }, "google_pay": { "type": [ "boolean", "null" ], "description": "Whether Google Pay is accepted at checkout." }, "cash_app_pay": { "type": [ "boolean", "null" ], "description": "Whether Cash App Pay is accepted at checkout." }, "afterpay_clearpay": { "type": [ "boolean", "null" ], "description": "Whether Afterpay/Clearpay is accepted at checkout." } } }, "AdditionalRecipient": { "type": "object", "description": "Represents an additional recipient (other than the merchant) receiving a portion of this tender.", "x-release-status": "DEPRECATED", "required": [ "location_id", "amount_money" ], "properties": { "location_id": { "type": "string", "description": "The location ID for a recipient (other than the merchant) receiving a portion of this tender.", "minLength": 1, "maxLength": 50 }, "description": { "type": [ "string", "null" ], "description": "The description of the additional recipient.", "maxLength": 100 }, "amount_money": { "$ref": "#/$defs/Money", "description": "The amount of money distributed to the recipient." }, "receivable_id": { "type": [ "string", "null" ], "description": "The unique ID for the RETIRED `AdditionalRecipientReceivable` object. This field should be empty for any `AdditionalRecipient` objects created after the retirement.", "maxLength": 192 } } }, "Address": { "type": "object", "description": "Represents a postal address in a country. \nFor more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "x-release-status": "PUBLIC", "properties": { "address_line_1": { "type": [ "string", "null" ], "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields)." }, "address_line_2": { "type": [ "string", "null" ], "description": "The second line of the address, if any." }, "address_line_3": { "type": [ "string", "null" ], "description": "The third line of the address, if any." }, "locality": { "type": [ "string", "null" ], "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)." }, "sublocality": { "type": [ "string", "null" ], "description": "A civil region within the address's `locality`, if any." }, "sublocality_2": { "type": [ "string", "null" ], "description": "A civil region within the address's `sublocality`, if any." }, "sublocality_3": { "type": [ "string", "null" ], "description": "A civil region within the address's `sublocality_2`, if any." }, "administrative_district_level_1": { "type": [ "string", "null" ], "description": "A civil entity within the address's country. In the US, this\nis the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)." }, "administrative_district_level_2": { "type": [ "string", "null" ], "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county." }, "administrative_district_level_3": { "type": [ "string", "null" ], "description": "A civil entity within the address's `administrative_district_level_2`,\nif any." }, "postal_code": { "type": [ "string", "null" ], "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)." }, "country": { "$ref": "#/$defs/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\nSee [Country](#type-country) for possible values" }, "first_name": { "type": [ "string", "null" ], "description": "Optional first name when it's representing recipient." }, "last_name": { "type": [ "string", "null" ], "description": "Optional last name when it's representing recipient." } } }, "Card": { "type": "object", "description": "Represents the payment details of a card to be used for payments. These\ndetails are determined by the payment token generated by Web Payments SDK.", "x-release-status": "PUBLIC", "properties": { "id": { "type": "string", "description": "Unique ID for this card. Generated by Square.", "maxLength": 64, "readOnly": true }, "card_brand": { "$ref": "#/$defs/CardBrand", "description": "The card's brand.\nSee [CardBrand](#type-cardbrand) for possible values", "readOnly": true }, "last_4": { "type": "string", "description": "The last 4 digits of the card number.", "maxLength": 4, "readOnly": true }, "exp_month": { "type": [ "integer", "null" ], "description": "The expiration month of the associated card as an integer between 1 and 12.", "format": "int64" }, "exp_year": { "type": [ "integer", "null" ], "description": "The four-digit year of the card's expiration date.", "format": "int64" }, "cardholder_name": { "type": [ "string", "null" ], "description": "The name of the cardholder.", "maxLength": 96 }, "billing_address": { "$ref": "#/$defs/Address", "description": "The billing address for this card." }, "fingerprint": { "type": "string", "description": "Intended as a Square-assigned identifier, based\non the card number, to identify the card across multiple locations within a\nsingle application.", "maxLength": 255, "readOnly": true }, "customer_id": { "type": [ "string", "null" ], "description": "**Required** The ID of a customer created using the Customers API to be associated with the card." }, "merchant_id": { "type": "string", "description": "The ID of the merchant associated with the card.", "readOnly": true }, "reference_id": { "type": [ "string", "null" ], "description": "An optional user-defined reference ID that associates this card with\nanother entity in an external system. For example, a customer ID from an\nexternal customer management system.", "maxLength": 128 }, "enabled": { "type": "boolean", "description": "Indicates whether or not a card can be used for payments.", "readOnly": true }, "card_type": { "$ref": "#/$defs/CardType", "description": "The type of the card.\nThe Card object includes this field only in response to Payments API calls.\nSee [CardType](#type-cardtype) for possible values", "readOnly": true }, "prepaid_type": { "$ref": "#/$defs/CardPrepaidType", "description": "Indicates whether the Card is prepaid or not.\nThe Card object includes this field only in response to Payments API calls.\nSee [CardPrepaidType](#type-cardprepaidtype) for possible values", "readOnly": true }, "bin": { "type": "string", "description": "The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API\nreturns this field.", "maxLength": 6, "readOnly": true }, "version": { "type": "integer", "description": "Current version number of the card. Increments with each card update. Requests to update an\nexisting Card object will be rejected unless the version in the request matches the current\nversion for the Card.", "format": "int64" }, "card_co_brand": { "$ref": "#/$defs/CardCoBrand", "description": "The card's co-brand if available. For example, an Afterpay virtual card would have a\nco-brand of AFTERPAY.\nSee [CardCoBrand](#type-cardcobrand) for possible values", "readOnly": true } } }, "CardBrand": { "type": "string", "enum": [ "OTHER_BRAND", "VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DISCOVER", "DISCOVER_DINERS", "JCB", "CHINA_UNIONPAY", "SQUARE_GIFT_CARD", "SQUARE_CAPITAL_CARD", "INTERAC", "EFTPOS", "FELICA", "EBT" ], "x-enum-elements": [ { "name": "OTHER_BRAND", "description": "" }, { "name": "VISA", "description": "" }, { "name": "MASTERCARD", "description": "" }, { "name": "AMERICAN_EXPRESS", "description": "" }, { "name": "DISCOVER", "description": "" }, { "name": "DISCOVER_DINERS", "description": "" }, { "name": "JCB", "description": "" }, { "name": "CHINA_UNIONPAY", "description": "" }, { "name": "SQUARE_GIFT_CARD", "description": "" }, { "name": "SQUARE_CAPITAL_CARD", "description": "" }, { "name": "INTERAC", "description": "" }, { "name": "EFTPOS", "description": "" }, { "name": "FELICA", "description": "" }, { "name": "EBT", "description": "" } ], "description": "Indicates a card's brand, such as `VISA` or `MASTERCARD`.", "x-release-status": "PUBLIC" }, "CardCoBrand": { "type": "string", "enum": [ "UNKNOWN", "AFTERPAY", "CLEARPAY" ], "x-enum-elements": [ { "name": "UNKNOWN", "description": "" }, { "name": "AFTERPAY", "description": "" }, { "name": "CLEARPAY", "description": "" } ], "description": "Indicates the brand for a co-branded card.", "x-release-status": "PUBLIC" }, "CardPrepaidType": { "type": "string", "enum": [ "UNKNOWN_PREPAID_TYPE", "NOT_PREPAID", "PREPAID" ], "x-enum-elements": [ { "name": "UNKNOWN_PREPAID_TYPE", "description": "" }, { "name": "NOT_PREPAID", "description": "" }, { "name": "PREPAID", "description": "" } ], "description": "Indicates a card's prepaid type, such as `NOT_PREPAID` or `PREPAID`.", "x-release-status": "PUBLIC" }, "CardType": { "type": "string", "enum": [ "UNKNOWN_CARD_TYPE", "CREDIT", "DEBIT" ], "x-enum-elements": [ { "name": "UNKNOWN_CARD_TYPE", "description": "" }, { "name": "CREDIT", "description": "" }, { "name": "DEBIT", "description": "" } ], "description": "Indicates a card's type, such as `CREDIT` or `DEBIT`.", "x-release-status": "PUBLIC" }, "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." } } }, "CheckoutOptions": { "type": "object", "x-release-status": "PUBLIC", "properties": { "allow_tipping": { "type": [ "boolean", "null" ], "description": "Indicates whether the payment allows tipping." }, "custom_fields": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CustomField" }, "description": "The custom fields requesting information from the buyer." }, "subscription_plan_id": { "type": [ "string", "null" ], "description": "The ID of the subscription plan for the buyer to pay and subscribe.\nFor more information, see [Subscription Plan Checkout](https://developer.squareup.com/docs/checkout-api/subscription-plan-checkout).", "maxLength": 255 }, "redirect_url": { "type": [ "string", "null" ], "description": "The confirmation page URL to redirect the buyer to after Square processes the payment.", "maxLength": 2048 }, "merchant_support_email": { "type": [ "string", "null" ], "description": "The email address that buyers can use to contact the seller.", "maxLength": 256 }, "ask_for_shipping_address": { "type": [ "boolean", "null" ], "description": "Indicates whether to include the address fields in the payment form." }, "accepted_payment_methods": { "$ref": "#/$defs/AcceptedPaymentMethods", "description": "The methods allowed for buyers during checkout." }, "app_fee_money": { "$ref": "#/$defs/Money", "description": "The amount of money that the developer is taking as a fee for facilitating the payment on behalf of the seller.\n\nThe amount cannot be more than 90% of the total amount of the payment.\n\nThe amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/common-data-types/working-with-monetary-amounts).\n\nThe fee currency code must match the currency associated with the seller that is accepting the payment. The application must be from a developer account in the same country and using the same currency code as the seller. For more information about the application fee scenario, see [Take Payments and Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees).\n\nTo set this field, `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required. For more information, see [Permissions](https://developer.squareup.com/docs/payments-api/collect-fees/additional-considerations#permissions)." }, "shipping_fee": { "$ref": "#/$defs/ShippingFee", "description": "The fee associated with shipping to be applied to the `Order` as a service charge." }, "enable_coupon": { "type": [ "boolean", "null" ], "description": "Indicates whether to include the `Add coupon` section for the buyer to provide a Square marketing coupon in the payment form." }, "enable_loyalty": { "type": [ "boolean", "null" ], "description": "Indicates whether to include the `REWARDS` section for the buyer to opt in to loyalty, redeem rewards in the payment form, or both." } } }, "Country": { "type": "string", "enum": [ "ZZ", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "x-enum-elements": [ { "name": "ZZ", "description": "Unknown" }, { "name": "AD", "description": "Andorra" }, { "name": "AE", "description": "United Arab Emirates" }, { "name": "AF", "description": "Afghanistan" }, { "name": "AG", "description": "Antigua and Barbuda" }, { "name": "AI", "description": "Anguilla" }, { "name": "AL", "description": "Albania" }, { "name": "AM", "description": "Armenia" }, { "name": "AO", "description": "Angola" }, { "name": "AQ", "description": "Antartica" }, { "name": "AR", "description": "Argentina" }, { "name": "AS", "description": "American Samoa" }, { "name": "AT", "description": "Austria" }, { "name": "AU", "description": "Australia" }, { "name": "AW", "description": "Aruba" }, { "name": "AX", "description": "Åland Islands" }, { "name": "AZ", "description": "Azerbaijan" }, { "name": "BA", "description": "Bosnia and Herzegovina" }, { "name": "BB", "description": "Barbados" }, { "name": "BD", "description": "Bangladesh" }, { "name": "BE", "description": "Belgium" }, { "name": "BF", "description": "Burkina Faso" }, { "name": "BG", "description": "Bulgaria" }, { "name": "BH", "description": "Bahrain" }, { "name": "BI", "description": "Burundi" }, { "name": "BJ", "description": "Benin" }, { "name": "BL", "description": "Saint Barthélemy" }, { "name": "BM", "description": "Bermuda" }, { "name": "BN", "description": "Brunei" }, { "name": "BO", "description": "Bolivia" }, { "name": "BQ", "description": "Bonaire" }, { "name": "BR", "description": "Brazil" }, { "name": "BS", "description": "Bahamas" }, { "name": "BT", "description": "Bhutan" }, { "name": "BV", "description": "Bouvet Island" }, { "name": "BW", "description": "Botswana" }, { "name": "BY", "description": "Belarus" }, { "name": "BZ", "description": "Belize" }, { "name": "CA", "description": "Canada" }, { "name": "CC", "description": "Cocos Islands" }, { "name": "CD", "description": "Democratic Republic of the Congo" }, { "name": "CF", "description": "Central African Republic" }, { "name": "CG", "description": "Congo" }, { "name": "CH", "description": "Switzerland" }, { "name": "CI", "description": "Ivory Coast" }, { "name": "CK", "description": "Cook Islands" }, { "name": "CL", "description": "Chile" }, { "name": "CM", "description": "Cameroon" }, { "name": "CN", "description": "China" }, { "name": "CO", "description": "Colombia" }, { "name": "CR", "description": "Costa Rica" }, { "name": "CU", "description": "Cuba" }, { "name": "CV", "description": "Cabo Verde" }, { "name": "CW", "description": "Curaçao" }, { "name": "CX", "description": "Christmas Island" }, { "name": "CY", "description": "Cyprus" }, { "name": "CZ", "description": "Czechia" }, { "name": "DE", "description": "Germany" }, { "name": "DJ", "description": "Djibouti" }, { "name": "DK", "description": "Denmark" }, { "name": "DM", "description": "Dominica" }, { "name": "DO", "description": "Dominican Republic" }, { "name": "DZ", "description": "Algeria" }, { "name": "EC", "description": "Ecuador" }, { "name": "EE", "description": "Estonia" }, { "name": "EG", "description": "Egypt" }, { "name": "EH", "description": "Western Sahara" }, { "name": "ER", "description": "Eritrea" }, { "name": "ES", "description": "Spain" }, { "name": "ET", "description": "Ethiopia" }, { "name": "FI", "description": "Finland" }, { "name": "FJ", "description": "Fiji" }, { "name": "FK", "description": "Falkland Islands" }, { "name": "FM", "description": "Federated States of Micronesia" }, { "name": "FO", "description": "Faroe Islands" }, { "name": "FR", "description": "France" }, { "name": "GA", "description": "Gabon" }, { "name": "GB", "description": "United Kingdom" }, { "name": "GD", "description": "Grenada" }, { "name": "GE", "description": "Georgia" }, { "name": "GF", "description": "French Guiana" }, { "name": "GG", "description": "Guernsey" }, { "name": "GH", "description": "Ghana" }, { "name": "GI", "description": "Gibraltar" }, { "name": "GL", "description": "Greenland" }, { "name": "GM", "description": "Gambia" }, { "name": "GN", "description": "Guinea" }, { "name": "GP", "description": "Guadeloupe" }, { "name": "GQ", "description": "Equatorial Guinea" }, { "name": "GR", "description": "Greece" }, { "name": "GS", "description": "South Georgia and the South Sandwich Islands" }, { "name": "GT", "description": "Guatemala" }, { "name": "GU", "description": "Guam" }, { "name": "GW", "description": "Guinea-Bissau" }, { "name": "GY", "description": "Guyana" }, { "name": "HK", "description": "Hong Kong" }, { "name": "HM", "description": "Heard Island and McDonald Islands" }, { "name": "HN", "description": "Honduras" }, { "name": "HR", "description": "Croatia" }, { "name": "HT", "description": "Haiti" }, { "name": "HU", "description": "Hungary" }, { "name": "ID", "description": "Indonesia" }, { "name": "IE", "description": "Ireland" }, { "name": "IL", "description": "Israel" }, { "name": "IM", "description": "Isle of Man" }, { "name": "IN", "description": "India" }, { "name": "IO", "description": "British Indian Ocean Territory" }, { "name": "IQ", "description": "Iraq" }, { "name": "IR", "description": "Iran" }, { "name": "IS", "description": "Iceland" }, { "name": "IT", "description": "Italy" }, { "name": "JE", "description": "Jersey" }, { "name": "JM", "description": "Jamaica" }, { "name": "JO", "description": "Jordan" }, { "name": "JP", "description": "Japan" }, { "name": "KE", "description": "Kenya" }, { "name": "KG", "description": "Kyrgyzstan" }, { "name": "KH", "description": "Cambodia" }, { "name": "KI", "description": "Kiribati" }, { "name": "KM", "description": "Comoros" }, { "name": "KN", "description": "Saint Kitts and Nevis" }, { "name": "KP", "description": "Democratic People's Republic of Korea" }, { "name": "KR", "description": "Republic of Korea" }, { "name": "KW", "description": "Kuwait" }, { "name": "KY", "description": "Cayman Islands" }, { "name": "KZ", "description": "Kazakhstan" }, { "name": "LA", "description": "Lao People's Democratic Republic" }, { "name": "LB", "description": "Lebanon" }, { "name": "LC", "description": "Saint Lucia" }, { "name": "LI", "description": "Liechtenstein" }, { "name": "LK", "description": "Sri Lanka" }, { "name": "LR", "description": "Liberia" }, { "name": "LS", "description": "Lesotho" }, { "name": "LT", "description": "Lithuania" }, { "name": "LU", "description": "Luxembourg" }, { "name": "LV", "description": "Latvia" }, { "name": "LY", "description": "Libya" }, { "name": "MA", "description": "Morocco" }, { "name": "MC", "description": "Monaco" }, { "name": "MD", "description": "Moldova" }, { "name": "ME", "description": "Montenegro" }, { "name": "MF", "description": "Saint Martin" }, { "name": "MG", "description": "Madagascar" }, { "name": "MH", "description": "Marshall Islands" }, { "name": "MK", "description": "North Macedonia" }, { "name": "ML", "description": "Mali" }, { "name": "MM", "description": "Myanmar" }, { "name": "MN", "description": "Mongolia" }, { "name": "MO", "description": "Macao" }, { "name": "MP", "description": "Northern Mariana Islands" }, { "name": "MQ", "description": "Martinique" }, { "name": "MR", "description": "Mauritania" }, { "name": "MS", "description": "Montserrat" }, { "name": "MT", "description": "Malta" }, { "name": "MU", "description": "Mauritius" }, { "name": "MV", "description": "Maldives" }, { "name": "MW", "description": "Malawi" }, { "name": "MX", "description": "Mexico" }, { "name": "MY", "description": "Malaysia" }, { "name": "MZ", "description": "Mozambique" }, { "name": "NA", "description": "Namibia" }, { "name": "NC", "description": "New Caledonia" }, { "name": "NE", "description": "Niger" }, { "name": "NF", "description": "Norfolk Island" }, { "name": "NG", "description": "Nigeria" }, { "name": "NI", "description": "Nicaragua" }, { "name": "NL", "description": "Netherlands" }, { "name": "NO", "description": "Norway" }, { "name": "NP", "description": "Nepal" }, { "name": "NR", "description": "Nauru" }, { "name": "NU", "description": "Niue" }, { "name": "NZ", "description": "New Zealand" }, { "name": "OM", "description": "Oman" }, { "name": "PA", "description": "Panama" }, { "name": "PE", "description": "Peru" }, { "name": "PF", "description": "French Polynesia" }, { "name": "PG", "description": "Papua New Guinea" }, { "name": "PH", "description": "Philippines" }, { "name": "PK", "description": "Pakistan" }, { "name": "PL", "description": "Poland" }, { "name": "PM", "description": "Saint Pierre and Miquelon" }, { "name": "PN", "description": "Pitcairn" }, { "name": "PR", "description": "Puerto Rico" }, { "name": "PS", "description": "Palestine" }, { "name": "PT", "description": "Portugal" }, { "name": "PW", "description": "Palau" }, { "name": "PY", "description": "Paraguay" }, { "name": "QA", "description": "Qatar" }, { "name": "RE", "description": "Réunion" }, { "name": "RO", "description": "Romania" }, { "name": "RS", "description": "Serbia" }, { "name": "RU", "description": "Russia" }, { "name": "RW", "description": "Rwanda" }, { "name": "SA", "description": "Saudi Arabia" }, { "name": "SB", "description": "Solomon Islands" }, { "name": "SC", "description": "Seychelles" }, { "name": "SD", "description": "Sudan" }, { "name": "SE", "description": "Sweden" }, { "name": "SG", "description": "Singapore" }, { "name": "SH", "description": "Saint Helena, Ascension and Tristan da Cunha" }, { "name": "SI", "description": "Slovenia" }, { "name": "SJ", "description": "Svalbard and Jan Mayen" }, { "name": "SK", "description": "Slovakia" }, { "name": "SL", "description": "Sierra Leone" }, { "name": "SM", "description": "San Marino" }, { "name": "SN", "description": "Senegal" }, { "name": "SO", "description": "Somalia" }, { "name": "SR", "description": "Suriname" }, { "name": "SS", "description": "South Sudan" }, { "name": "ST", "description": "Sao Tome and Principe" }, { "name": "SV", "description": "El Salvador" }, { "name": "SX", "description": "Sint Maarten" }, { "name": "SY", "description": "Syrian Arab Republic" }, { "name": "SZ", "description": "Eswatini" }, { "name": "TC", "description": "Turks and Caicos Islands" }, { "name": "TD", "description": "Chad" }, { "name": "TF", "description": "French Southern Territories" }, { "name": "TG", "description": "Togo" }, { "name": "TH", "description": "Thailand" }, { "name": "TJ", "description": "Tajikistan" }, { "name": "TK", "description": "Tokelau" }, { "name": "TL", "description": "Timor-Leste" }, { "name": "TM", "description": "Turkmenistan" }, { "name": "TN", "description": "Tunisia" }, { "name": "TO", "description": "Tonga" }, { "name": "TR", "description": "Turkey" }, { "name": "TT", "description": "Trinidad and Tobago" }, { "name": "TV", "description": "Tuvalu" }, { "name": "TW", "description": "Taiwan" }, { "name": "TZ", "description": "Tanzania" }, { "name": "UA", "description": "Ukraine" }, { "name": "UG", "description": "Uganda" }, { "name": "UM", "description": "United States Minor Outlying Islands" }, { "name": "US", "description": "United States of America" }, { "name": "UY", "description": "Uruguay" }, { "name": "UZ", "description": "Uzbekistan" }, { "name": "VA", "description": "Vatican City" }, { "name": "VC", "description": "Saint Vincent and the Grenadines" }, { "name": "VE", "description": "Venezuela" }, { "name": "VG", "description": "British Virgin Islands" }, { "name": "VI", "description": "U.S. Virgin Islands" }, { "name": "VN", "description": "Vietnam" }, { "name": "VU", "description": "Vanuatu" }, { "name": "WF", "description": "Wallis and Futuna" }, { "name": "WS", "description": "Samoa" }, { "name": "YE", "description": "Yemen" }, { "name": "YT", "description": "Mayotte" }, { "name": "ZA", "description": "South Africa" }, { "name": "ZM", "description": "Zambia" }, { "name": "ZW", "description": "Zimbabwe" } ], "description": "Indicates the country associated with another entity, such as a business.\nValues are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm).", "x-release-status": "PUBLIC" }, "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" }, "CustomField": { "type": "object", "description": "Describes a custom form field to add to the checkout page to collect more information from buyers during checkout.\nFor more information,\nsee [Specify checkout options](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations#specify-checkout-options-1).", "x-release-status": "PUBLIC", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "The title of the custom field.", "minLength": 1, "maxLength": 50 } } }, "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" }, "Fulfillment": { "type": "object", "description": "Contains details about how to fulfill this order.\nOrders can only be created with at most one fulfillment using the API.\nHowever, orders returned by the Orders API might contain multiple fulfillments because sellers can create multiple fulfillments using Square products such as Square Online.", "x-release-status": "PUBLIC", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the fulfillment only within this order.", "maxLength": 60, "x-release-status": "BETA" }, "type": { "$ref": "#/$defs/FulfillmentType", "description": "The type of the fulfillment.\nSee [FulfillmentType](#type-fulfillmenttype) for possible values" }, "state": { "$ref": "#/$defs/FulfillmentState", "description": "The state of the fulfillment.\nSee [FulfillmentState](#type-fulfillmentstate) for possible values" }, "line_item_application": { "$ref": "#/$defs/FulfillmentFulfillmentLineItemApplication", "description": "Describes what order line items this fulfillment applies to.\nIt can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment entries.\nSee [FulfillmentFulfillmentLineItemApplication](#type-fulfillmentfulfillmentlineitemapplication) for possible values", "readOnly": true, "x-release-status": "BETA" }, "entries": { "type": "array", "items": { "$ref": "#/$defs/FulfillmentFulfillmentEntry" }, "description": "A list of entries pertaining to the fulfillment of an order. Each entry must reference\na valid `uid` for an order line item in the `line_item_uid` field, as well as a `quantity` to\nfulfill.\n\nMultiple entries can reference the same line item `uid`, as long as the total quantity among\nall fulfillment entries referencing a single line item does not exceed the quantity of the\norder's line item itself.\n\nAn order cannot be marked as `COMPLETED` before all fulfillments are `COMPLETED`,\n`CANCELED`, or `FAILED`. Fulfillments can be created and completed independently\nbefore order completion.", "readOnly": true, "x-release-status": "BETA" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this fulfillment. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "x-release-status": "BETA" }, "pickup_details": { "$ref": "#/$defs/FulfillmentPickupDetails", "description": "Contains details for a pickup fulfillment. These details are required when the fulfillment\ntype is `PICKUP`." }, "shipment_details": { "$ref": "#/$defs/FulfillmentShipmentDetails", "description": "Contains details for a shipment fulfillment. These details are required when the fulfillment type\nis `SHIPMENT`.\n\nA shipment fulfillment's relationship to fulfillment `state`:\n`PROPOSED`: A shipment is requested.\n`RESERVED`: Fulfillment in progress. Shipment processing.\n`PREPARED`: Shipment packaged. Shipping label created.\n`COMPLETED`: Package has been shipped.\n`CANCELED`: Shipment has been canceled.\n`FAILED`: Shipment has failed.", "x-release-status": "BETA" }, "delivery_details": { "$ref": "#/$defs/FulfillmentDeliveryDetails", "description": "Describes delivery details of an order fulfillment.", "x-release-status": "BETA" } } }, "FulfillmentDeliveryDetails": { "type": "object", "description": "Describes delivery details of an order fulfillment.", "x-release-status": "BETA", "properties": { "recipient": { "$ref": "#/$defs/FulfillmentRecipient", "description": "The contact information for the person to receive the fulfillment." }, "schedule_type": { "$ref": "#/$defs/FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType", "description": "Indicates the fulfillment delivery schedule type. If `SCHEDULED`, then\n`deliver_at` is required. If `ASAP`, then `prep_time_duration` is required. The default is `SCHEDULED`.\nSee [OrderFulfillmentDeliveryDetailsScheduleType](#type-orderfulfillmentdeliverydetailsscheduletype) for possible values" }, "placed_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was placed.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").\n\nMust be in RFC 3339 timestamp format, e.g., \"2016-09-04T23:59:33.123Z\".", "readOnly": true }, "deliver_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nthat represents the start of the delivery period.\nWhen the fulfillment `schedule_type` is `ASAP`, the field is automatically\nset to the current time plus the `prep_time_duration`.\nOtherwise, the application can set this field while the fulfillment `state` is\n`PROPOSED`, `RESERVED`, or `PREPARED` (any time before the\nterminal state such as `COMPLETED`, `CANCELED`, and `FAILED`).\n\nThe timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\")." }, "prep_time_duration": { "type": [ "string", "null" ], "description": "The duration of time it takes to prepare and deliver this fulfillment.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\")." }, "delivery_window_duration": { "type": [ "string", "null" ], "description": "The time period after `deliver_at` in which to deliver the order.\nApplications can set this field when the fulfillment `state` is\n`PROPOSED`, `RESERVED`, or `PREPARED` (any time before the terminal state\nsuch as `COMPLETED`, `CANCELED`, and `FAILED`).\n\nThe duration must be in RFC 3339 format (for example, \"P1W3D\")." }, "note": { "type": [ "string", "null" ], "description": "Provides additional instructions about the delivery fulfillment.\nIt is displayed in the Square Point of Sale application and set by the API.", "maxLength": 550 }, "completed_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicates when the seller completed the fulfillment.\nThis field is automatically set when fulfillment `state` changes to `COMPLETED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")." }, "in_progress_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicates when the seller started processing the fulfillment.\nThis field is automatically set when the fulfillment `state` changes to `RESERVED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "rejected_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was rejected. This field is\nautomatically set when the fulfillment `state` changes to `FAILED`.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "ready_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the seller marked the fulfillment as ready for\ncourier pickup. This field is automatically set when the fulfillment `state` changes\nto PREPARED.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "delivered_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was delivered to the recipient.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "canceled_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was canceled. This field is automatically\nset when the fulfillment `state` changes to `CANCELED`.\n\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "cancel_reason": { "type": [ "string", "null" ], "description": "The delivery cancellation reason. Max length: 100 characters.", "maxLength": 100 }, "courier_pickup_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when an order can be picked up by the courier for delivery.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")." }, "courier_pickup_window_duration": { "type": [ "string", "null" ], "description": "The time period after `courier_pickup_at` in which the courier should pick up the order.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\")." }, "is_no_contact_delivery": { "type": [ "boolean", "null" ], "description": "Whether the delivery is preferred to be no contact." }, "dropoff_notes": { "type": [ "string", "null" ], "description": "A note to provide additional instructions about how to deliver the order.", "maxLength": 550 }, "courier_provider_name": { "type": [ "string", "null" ], "description": "The name of the courier provider.", "maxLength": 255 }, "courier_support_phone_number": { "type": [ "string", "null" ], "description": "The support phone number of the courier.", "maxLength": 17 }, "square_delivery_id": { "type": [ "string", "null" ], "description": "The identifier for the delivery created by Square.", "maxLength": 50 }, "external_delivery_id": { "type": [ "string", "null" ], "description": "The identifier for the delivery created by the third-party courier service.", "maxLength": 50 }, "managed_delivery": { "type": [ "boolean", "null" ], "description": "The flag to indicate the delivery is managed by a third party (ie DoorDash), which means\nwe may not receive all recipient information for PII purposes." } } }, "FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType": { "type": "string", "enum": [ "SCHEDULED", "ASAP" ], "x-enum-elements": [ { "name": "SCHEDULED", "description": "Indicates the fulfillment to deliver at a scheduled deliver time." }, { "name": "ASAP", "description": "Indicates that the fulfillment to deliver as soon as possible and should be prepared\nimmediately." } ], "description": "The schedule type of the delivery fulfillment.", "x-release-status": "BETA" }, "FulfillmentFulfillmentEntry": { "type": "object", "description": "Links an order line item to a fulfillment. Each entry must reference\na valid `uid` for an order line item in the `line_item_uid` field, as well as a `quantity` to\nfulfill.", "x-release-status": "BETA", "required": [ "line_item_uid", "quantity" ], "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the fulfillment entry only within this order.", "maxLength": 60 }, "line_item_uid": { "type": "string", "description": "The `uid` from the order line item.", "minLength": 1 }, "quantity": { "type": "string", "description": "The quantity of the line item being fulfilled, formatted as a decimal number.\nFor example, `\"3\"`.\n\nFulfillments for line items with a `quantity_unit` can have non-integer quantities.\nFor example, `\"1.70000\"`.", "minLength": 1, "maxLength": 12 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this fulfillment entry. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata)." } } }, "FulfillmentFulfillmentLineItemApplication": { "type": "string", "enum": [ "ALL", "ENTRY_LIST" ], "x-enum-elements": [ { "name": "ALL", "description": "If `ALL`, `entries` must be unset." }, { "name": "ENTRY_LIST", "description": "If `ENTRY_LIST`, supply a list of `entries`." } ], "description": "The `line_item_application` describes what order line items this fulfillment applies\nto. It can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment entries.", "x-release-status": "BETA" }, "FulfillmentPickupDetails": { "type": "object", "description": "Contains details necessary to fulfill a pickup order.", "x-release-status": "PUBLIC", "properties": { "recipient": { "$ref": "#/$defs/FulfillmentRecipient", "description": "Information about the person to pick up this fulfillment from a physical\nlocation." }, "expires_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment expires if it is not marked in progress. The timestamp must be\nin RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\"). The expiration time can only be set\nup to 7 days in the future. If `expires_at` is not set, any new payments attached to the order\nare automatically completed." }, "auto_complete_duration": { "type": [ "string", "null" ], "description": "The duration of time after which an in progress pickup fulfillment is automatically moved\nto the `COMPLETED` state. The duration must be in RFC 3339 format (for example, \"P1W3D\").\n\nIf not set, this pickup fulfillment remains in progress until it is canceled or completed." }, "schedule_type": { "$ref": "#/$defs/FulfillmentPickupDetailsScheduleType", "description": "The schedule type of the pickup fulfillment. Defaults to `SCHEDULED`.\nSee [FulfillmentPickupDetailsScheduleType](#type-fulfillmentpickupdetailsscheduletype) for possible values" }, "pickup_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nthat represents the start of the pickup window. Must be in RFC 3339 timestamp format, e.g.,\n\"2016-09-04T23:59:33.123Z\".\n\nFor fulfillments with the schedule type `ASAP`, this is automatically set\nto the current time plus the expected duration to prepare the fulfillment." }, "pickup_window_duration": { "type": [ "string", "null" ], "description": "The window of time in which the order should be picked up after the `pickup_at` timestamp.\nMust be in RFC 3339 duration format, e.g., \"P1W3D\". Can be used as an\ninformational guideline for merchants." }, "prep_time_duration": { "type": [ "string", "null" ], "description": "The duration of time it takes to prepare this fulfillment.\nThe duration must be in RFC 3339 format (for example, \"P1W3D\")." }, "note": { "type": [ "string", "null" ], "description": "A note to provide additional instructions about the pickup\nfulfillment displayed in the Square Point of Sale application and set by the API.", "maxLength": 500 }, "placed_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was placed. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "accepted_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was marked in progress. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "rejected_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was rejected. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "ready_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment is marked as ready for pickup. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "expired_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment expired. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "picked_up_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was picked up by the recipient. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "canceled_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the fulfillment was canceled. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "cancel_reason": { "type": [ "string", "null" ], "description": "A description of why the pickup was canceled. The maximum length: 100 characters.", "maxLength": 100 }, "is_curbside_pickup": { "type": [ "boolean", "null" ], "description": "If set to `true`, indicates that this pickup order is for curbside pickup, not in-store pickup.", "x-release-status": "BETA" }, "curbside_pickup_details": { "$ref": "#/$defs/FulfillmentPickupDetailsCurbsidePickupDetails", "description": "Specific details for curbside pickup. These details can only be populated if `is_curbside_pickup` is set to `true`.", "x-release-status": "BETA" } } }, "FulfillmentPickupDetailsCurbsidePickupDetails": { "type": "object", "description": "Specific details for curbside pickup.", "x-release-status": "BETA", "properties": { "curbside_details": { "type": [ "string", "null" ], "description": "Specific details for curbside pickup, such as parking number and vehicle model.", "maxLength": 250 }, "buyer_arrived_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the buyer arrived and is waiting for pickup. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\")." } } }, "FulfillmentPickupDetailsScheduleType": { "type": "string", "enum": [ "SCHEDULED", "ASAP" ], "x-enum-elements": [ { "name": "SCHEDULED", "description": "Indicates that the fulfillment will be picked up at a scheduled pickup time." }, { "name": "ASAP", "description": "Indicates that the fulfillment will be picked up as soon as possible and\nshould be prepared immediately." } ], "description": "The schedule type of the pickup fulfillment.", "x-release-status": "PUBLIC" }, "FulfillmentRecipient": { "type": "object", "description": "Information about the fulfillment recipient.", "x-release-status": "PUBLIC", "properties": { "customer_id": { "type": [ "string", "null" ], "description": "The ID of the customer associated with the fulfillment.\n\nIf `customer_id` is provided, the fulfillment recipient's `display_name`,\n`email_address`, and `phone_number` are automatically populated from the\ntargeted customer profile. If these fields are set in the request, the request\nvalues override the information from the customer profile. If the\ntargeted customer profile does not contain the necessary information and\nthese fields are left unset, the request results in an error.", "maxLength": 191 }, "display_name": { "type": [ "string", "null" ], "description": "The display name of the fulfillment recipient. This field is required.\n\nIf provided, the display name overrides the corresponding customer profile value\nindicated by `customer_id`.", "maxLength": 255 }, "email_address": { "type": [ "string", "null" ], "description": "The email address of the fulfillment recipient.\n\nIf provided, the email address overrides the corresponding customer profile value\nindicated by `customer_id`.", "maxLength": 255 }, "phone_number": { "type": [ "string", "null" ], "description": "The phone number of the fulfillment recipient. This field is required.\n\nIf provided, the phone number overrides the corresponding customer profile value\nindicated by `customer_id`.", "maxLength": 17 }, "address": { "$ref": "#/$defs/Address", "description": "The address of the fulfillment recipient. This field is required.\n\nIf provided, the address overrides the corresponding customer profile value\nindicated by `customer_id`.", "x-release-status": "BETA" } } }, "FulfillmentShipmentDetails": { "type": "object", "description": "Contains the details necessary to fulfill a shipment order.", "x-release-status": "BETA", "properties": { "recipient": { "$ref": "#/$defs/FulfillmentRecipient", "description": "Information about the person to receive this shipment fulfillment." }, "carrier": { "type": [ "string", "null" ], "description": "The shipping carrier being used to ship this fulfillment (such as UPS, FedEx, or USPS).", "maxLength": 50 }, "shipping_note": { "type": [ "string", "null" ], "description": "A note with additional information for the shipping carrier.", "maxLength": 500 }, "shipping_type": { "type": [ "string", "null" ], "description": "A description of the type of shipping product purchased from the carrier\n(such as First Class, Priority, or Express).", "maxLength": 50 }, "tracking_number": { "type": [ "string", "null" ], "description": "The reference number provided by the carrier to track the shipment's progress.", "maxLength": 100 }, "tracking_url": { "type": [ "string", "null" ], "description": "A link to the tracking webpage on the carrier's website.", "maxLength": 2000 }, "placed_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment was requested. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "in_progress_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `RESERVED` state, which indicates that preparation\nof this shipment has begun. The timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "packaged_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `PREPARED` state, which indicates that the\nfulfillment is packaged. The timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "expected_shipped_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment is expected to be delivered to the shipping carrier.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")." }, "shipped_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when this fulfillment was moved to the `COMPLETED` state, which indicates that\nthe fulfillment has been given to the shipping carrier. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "canceled_at": { "type": [ "string", "null" ], "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating the shipment was canceled.\nThe timestamp must be in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")." }, "cancel_reason": { "type": [ "string", "null" ], "description": "A description of why the shipment was canceled.", "maxLength": 100 }, "failed_at": { "type": "string", "description": "The [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)\nindicating when the shipment failed to be completed. The timestamp must be in RFC 3339 format\n(for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "failure_reason": { "type": [ "string", "null" ], "description": "A description of why the shipment failed to be completed.", "maxLength": 100 } } }, "FulfillmentState": { "type": "string", "enum": [ "PROPOSED", "RESERVED", "PREPARED", "COMPLETED", "CANCELED", "FAILED" ], "x-enum-elements": [ { "name": "PROPOSED", "description": "Indicates that the fulfillment has been proposed." }, { "name": "RESERVED", "description": "Indicates that the fulfillment has been reserved." }, { "name": "PREPARED", "description": "Indicates that the fulfillment has been prepared." }, { "name": "COMPLETED", "description": "Indicates that the fulfillment was successfully completed." }, { "name": "CANCELED", "description": "Indicates that the fulfillment was canceled." }, { "name": "FAILED", "description": "Indicates that the fulfillment failed to be completed, but was not explicitly\ncanceled." } ], "description": "The current state of this fulfillment.", "x-release-status": "PUBLIC" }, "FulfillmentType": { "type": "string", "enum": [ "PICKUP", "SHIPMENT", "DELIVERY" ], "x-enum-elements": [ { "name": "PICKUP", "description": "A recipient to pick up the fulfillment from a physical [location](entity:Location)." }, { "name": "SHIPMENT", "description": "A shipping carrier to ship the fulfillment." }, { "name": "DELIVERY", "description": "A courier to deliver the fulfillment." } ], "description": "The type of fulfillment.", "x-release-status": "PUBLIC" }, "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" } } }, "Order": { "type": "object", "description": "Contains all information related to a single order to process with Square,\nincluding line items that specify the products to purchase. `Order` objects also\ninclude information about any associated tenders, refunds, and returns.\n\nAll Connect V2 Transactions have all been converted to Orders including all associated\nitemization data.", "x-release-status": "PUBLIC", "required": [ "location_id" ], "properties": { "id": { "type": "string", "description": "The order's unique ID.", "readOnly": true }, "location_id": { "type": "string", "description": "The ID of the seller location that this order is associated with.", "minLength": 1 }, "reference_id": { "type": [ "string", "null" ], "description": "A client-specified ID to associate an entity in another system\nwith this order.", "maxLength": 40 }, "source": { "$ref": "#/$defs/OrderSource", "description": "The origination details of the order." }, "customer_id": { "type": [ "string", "null" ], "description": "The ID of the [customer](entity:Customer) associated with the order.\n\nYou should specify a `customer_id` on the order (or the payment) to ensure that transactions\nare reliably linked to customers. Omitting this field might result in the creation of new\n[instant profiles](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles).", "maxLength": 191, "x-release-status": "BETA" }, "line_items": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItem" }, "description": "The line items included in the order." }, "taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemTax" }, "description": "The list of all taxes associated with the order.\n\nTaxes can be scoped to either `ORDER` or `LINE_ITEM`. For taxes with `LINE_ITEM` scope, an\n`OrderLineItemAppliedTax` must be added to each line item that the tax applies to. For taxes\nwith `ORDER` scope, the server generates an `OrderLineItemAppliedTax` for every line item.\n\nOn reads, each tax in the list includes the total amount of that tax applied to the order.\n\n__IMPORTANT__: If `LINE_ITEM` scope is set on any taxes in this field, using the deprecated\n`line_items.taxes` field results in an error. Use `line_items.applied_taxes`\ninstead." }, "discounts": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemDiscount" }, "description": "The list of all discounts associated with the order.\n\nDiscounts can be scoped to either `ORDER` or `LINE_ITEM`. For discounts scoped to `LINE_ITEM`,\nan `OrderLineItemAppliedDiscount` must be added to each line item that the discount applies to.\nFor discounts with `ORDER` scope, the server generates an `OrderLineItemAppliedDiscount`\nfor every line item.\n\n__IMPORTANT__: If `LINE_ITEM` scope is set on any discounts in this field, using the deprecated\n`line_items.discounts` field results in an error. Use `line_items.applied_discounts`\ninstead." }, "service_charges": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderServiceCharge" }, "description": "A list of service charges applied to the order." }, "fulfillments": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/Fulfillment" }, "description": "Details about order fulfillment.\n\nOrders can only be created with at most one fulfillment. However, orders returned\nby the API might contain multiple fulfillments." }, "returns": { "type": "array", "items": { "$ref": "#/$defs/OrderReturn" }, "description": "A collection of items from sale orders being returned in this one. Normally part of an\nitemized return or exchange. There is exactly one `Return` object per sale `Order` being\nreferenced.", "readOnly": true, "x-release-status": "BETA" }, "return_amounts": { "$ref": "#/$defs/OrderMoneyAmounts", "description": "The rollup of the returned money amounts.", "readOnly": true, "x-release-status": "BETA" }, "net_amounts": { "$ref": "#/$defs/OrderMoneyAmounts", "description": "The net money amounts (sale money - return money).", "readOnly": true, "x-release-status": "BETA" }, "rounding_adjustment": { "$ref": "#/$defs/OrderRoundingAdjustment", "description": "A positive rounding adjustment to the total of the order. This adjustment is commonly\nused to apply cash rounding when the minimum unit of account is smaller than the lowest physical\ndenomination of the currency.", "readOnly": true, "x-release-status": "BETA" }, "tenders": { "type": "array", "items": { "$ref": "#/$defs/Tender" }, "description": "The tenders that were used to pay for the order.", "readOnly": true, "x-release-status": "BETA" }, "refunds": { "type": "array", "items": { "$ref": "#/$defs/Refund" }, "description": "The refunds that are part of this order.", "readOnly": true, "x-release-status": "BETA" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this order. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "x-release-status": "BETA" }, "created_at": { "type": "string", "description": "The timestamp for when the order was created, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "updated_at": { "type": "string", "description": "The timestamp for when the order was last updated, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "closed_at": { "type": "string", "description": "The timestamp for when the order reached a terminal [state](entity:OrderState), in RFC 3339 format (for example \"2016-09-04T23:59:33.123Z\").", "readOnly": true }, "state": { "$ref": "#/$defs/OrderState", "description": "The current state of the order.\nSee [OrderState](#type-orderstate) for possible values" }, "version": { "type": "integer", "description": "The version number, which is incremented each time an update is committed to the order.\nOrders not created through the API do not include a version number and\ntherefore cannot be updated.\n\n[Read more about working with versions](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders).", "x-release-status": "BETA" }, "total_money": { "$ref": "#/$defs/Money", "description": "The total amount of money to collect for the order.", "readOnly": true }, "total_tax_money": { "$ref": "#/$defs/Money", "description": "The total amount of tax money to collect for the order.", "readOnly": true }, "total_discount_money": { "$ref": "#/$defs/Money", "description": "The total amount of discount money to collect for the order.", "readOnly": true }, "total_tip_money": { "$ref": "#/$defs/Money", "description": "The total amount of tip money to collect for the order.", "readOnly": true }, "total_service_charge_money": { "$ref": "#/$defs/Money", "description": "The total amount of money collected in service charges for the order.\n\nNote: `total_service_charge_money` is the sum of `applied_money` fields for each individual\nservice charge. Therefore, `total_service_charge_money` only includes inclusive tax amounts,\nnot additive tax amounts.", "readOnly": true }, "ticket_name": { "type": [ "string", "null" ], "description": "A short-term identifier for the order (such as a customer first name,\ntable number, or auto-generated order number that resets daily).", "maxLength": 30, "x-release-status": "BETA" }, "pricing_options": { "$ref": "#/$defs/OrderPricingOptions", "description": "Pricing options for an order. The options affect how the order's price is calculated.\nThey can be used, for example, to apply automatic price adjustments that are based on\npreconfigured [pricing rules](entity:CatalogPricingRule)." }, "rewards": { "type": "array", "items": { "$ref": "#/$defs/OrderReward" }, "description": "A set-like list of Rewards that have been added to the Order.", "readOnly": true, "x-release-status": "BETA" }, "net_amount_due_money": { "$ref": "#/$defs/Money", "description": "The net amount of money due on the order.", "readOnly": true } } }, "OrderLineItem": { "type": "object", "description": "Represents a line item in an order. Each line item describes a different\nproduct to purchase, with its own quantity and price details.", "x-release-status": "PUBLIC", "required": [ "quantity" ], "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the line item only within this order.", "maxLength": 60, "x-release-status": "BETA" }, "name": { "type": [ "string", "null" ], "description": "The name of the line item.", "maxLength": 512 }, "quantity": { "type": "string", "description": "The count, or measurement, of a line item being purchased:\n\nIf `quantity` is a whole number, and `quantity_unit` is not specified, then `quantity` denotes an item count. For example: `3` apples.\n\nIf `quantity` is a whole or decimal number, and `quantity_unit` is also specified, then `quantity` denotes a measurement. For example: `2.25` pounds of broccoli.\n\nFor more information, see [Specify item quantity and measurement unit](https://developer.squareup.com/docs/orders-api/create-orders#specify-item-quantity-and-measurement-unit).\n\nLine items with a quantity of `0` are automatically removed\nwhen paying for or otherwise completing the order.", "minLength": 1, "maxLength": 12 }, "quantity_unit": { "$ref": "#/$defs/OrderQuantityUnit", "description": "The measurement unit and decimal precision that this line item's quantity is measured in." }, "note": { "type": [ "string", "null" ], "description": "An optional note associated with the line item.", "maxLength": 2000 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The [CatalogItemVariation](entity:CatalogItemVariation) ID applied to this line item.", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this line item references.", "format": "int64" }, "variation_name": { "type": [ "string", "null" ], "description": "The name of the variation applied to this line item.", "maxLength": 400 }, "item_type": { "$ref": "#/$defs/OrderLineItemItemType", "description": "The type of line item: an itemized sale, a non-itemized sale (custom amount), or the\nactivation or reloading of a gift card.\nSee [OrderLineItemItemType](#type-orderlineitemitemtype) for possible values" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this line item. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "x-release-status": "BETA" }, "modifiers": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemModifier" }, "description": "The [CatalogModifier](entity:CatalogModifier)s applied to this line item." }, "applied_taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedTax" }, "description": "The list of references to taxes applied to this line item. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a\ntop-level `OrderLineItemTax` applied to the line item. On reads, the\namount applied is populated.\n\nAn `OrderLineItemAppliedTax` is automatically created on every line\nitem for all `ORDER` scoped taxes added to the order. `OrderLineItemAppliedTax`\nrecords for `LINE_ITEM` scoped taxes must be added in requests for the tax\nto apply to any line items.\n\nTo change the amount of a tax, modify the referenced top-level tax.", "x-release-status": "BETA" }, "applied_discounts": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedDiscount" }, "description": "The list of references to discounts applied to this line item. Each\n`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level\n`OrderLineItemDiscounts` applied to the line item. On reads, the amount\napplied is populated.\n\nAn `OrderLineItemAppliedDiscount` is automatically created on every line item for all\n`ORDER` scoped discounts that are added to the order. `OrderLineItemAppliedDiscount` records\nfor `LINE_ITEM` scoped discounts must be added in requests for the discount to apply to any\nline items.\n\nTo change the amount of a discount, modify the referenced top-level discount.", "x-release-status": "BETA" }, "applied_service_charges": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedServiceCharge" }, "description": "The list of references to service charges applied to this line item. Each\n`OrderLineItemAppliedServiceCharge` has a `service_charge_id` that references the `uid` of a\ntop-level `OrderServiceCharge` applied to the line item. On reads, the amount applied is\npopulated.\n\nTo change the amount of a service charge, modify the referenced top-level service charge.", "x-release-status": "BETA" }, "base_price_money": { "$ref": "#/$defs/Money", "description": "The base price for a single unit of the line item." }, "variation_total_price_money": { "$ref": "#/$defs/Money", "description": "The total price of all item variations sold in this line item.\nThe price is calculated as `base_price_money` multiplied by `quantity`.\nIt does not include modifiers.", "readOnly": true }, "gross_sales_money": { "$ref": "#/$defs/Money", "description": "The amount of money made in gross sales for this line item.\nThe amount is calculated as the sum of the variation's total price and each modifier's total price.\nFor inclusive tax items in the US, Canada, and Japan, tax is deducted from `gross_sales_money`. For Europe and\nAustralia, inclusive tax remains as part of the gross sale calculation.", "readOnly": true }, "total_tax_money": { "$ref": "#/$defs/Money", "description": "The total amount of tax money to collect for the line item.", "readOnly": true }, "total_discount_money": { "$ref": "#/$defs/Money", "description": "The total amount of discount money to collect for the line item.", "readOnly": true }, "total_money": { "$ref": "#/$defs/Money", "description": "The total amount of money to collect for this line item.", "readOnly": true }, "pricing_blocklists": { "$ref": "#/$defs/OrderLineItemPricingBlocklists", "description": "Describes pricing adjustments that are blocked from automatic\napplication to a line item. For more information, see\n[Apply Taxes and Discounts](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts).", "x-release-status": "BETA" }, "total_service_charge_money": { "$ref": "#/$defs/Money", "description": "The total amount of apportioned service charge money to collect for the line item.", "readOnly": true, "x-release-status": "BETA" } } }, "OrderLineItemAppliedDiscount": { "type": "object", "description": "Represents an applied portion of a discount to a line item in an order.\n\nOrder scoped discounts have automatically applied discounts present for each line item.\nLine-item scoped discounts must have applied discounts added manually for any applicable line\nitems. The corresponding applied money is automatically computed based on participating\nline items.", "x-release-status": "BETA", "required": [ "discount_uid" ], "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the applied discount only within this order.", "maxLength": 60 }, "discount_uid": { "type": "string", "description": "The `uid` of the discount that the applied discount represents. It must\nreference a discount present in the `order.discounts` field.\n\nThis field is immutable. To change which discounts apply to a line item,\nyou must delete the discount and re-add it as a new `OrderLineItemAppliedDiscount`.", "minLength": 1, "maxLength": 60 }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of money applied by the discount to the line item.", "readOnly": true } } }, "OrderLineItemAppliedServiceCharge": { "type": "object", "x-release-status": "BETA", "required": [ "service_charge_uid" ], "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the applied service charge only within this order.", "maxLength": 60 }, "service_charge_uid": { "type": "string", "description": "The `uid` of the service charge that the applied service charge represents. It must\nreference a service charge present in the `order.service_charges` field.\n\nThis field is immutable. To change which service charges apply to a line item,\ndelete and add a new `OrderLineItemAppliedServiceCharge`.", "minLength": 1, "maxLength": 60 }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of money applied by the service charge to the line item.", "readOnly": true } } }, "OrderLineItemAppliedTax": { "type": "object", "description": "Represents an applied portion of a tax to a line item in an order.\n\nOrder-scoped taxes automatically include the applied taxes in each line item.\nLine item taxes must be referenced from any applicable line items.\nThe corresponding applied money is automatically computed, based on the\nset of participating line items.", "x-release-status": "BETA", "required": [ "tax_uid" ], "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the applied tax only within this order.", "maxLength": 60 }, "tax_uid": { "type": "string", "description": "The `uid` of the tax for which this applied tax represents. It must reference\na tax present in the `order.taxes` field.\n\nThis field is immutable. To change which taxes apply to a line item, delete and add a new\n`OrderLineItemAppliedTax`.", "minLength": 1, "maxLength": 60 }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of money applied by the tax to the line item.", "readOnly": true } } }, "OrderLineItemDiscount": { "type": "object", "description": "Represents a discount that applies to one or more line items in an\norder.\n\nFixed-amount, order-scoped discounts are distributed across all non-zero line item totals.\nThe amount distributed to each line item is relative to the\namount contributed by the item to the order subtotal.", "x-release-status": "PUBLIC", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the discount only within this order.", "maxLength": 60, "x-release-status": "BETA" }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing [CatalogDiscount](entity:CatalogDiscount).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this discount references.", "format": "int64" }, "name": { "type": [ "string", "null" ], "description": "The discount's name.", "maxLength": 255 }, "type": { "$ref": "#/$defs/OrderLineItemDiscountType", "description": "The type of the discount.\n\nDiscounts that do not reference a catalog object ID must have a type of\n`FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\nSee [OrderLineItemDiscountType](#type-orderlineitemdiscounttype) for possible values" }, "percentage": { "type": [ "string", "null" ], "description": "The percentage of the discount, as a string representation of a decimal number.\nA value of `7.25` corresponds to a percentage of 7.25%.\n\n`percentage` is not set for amount-based discounts.", "maxLength": 10 }, "amount_money": { "$ref": "#/$defs/Money", "description": "The total declared monetary amount of the discount.\n\n`amount_money` is not set for percentage-based discounts." }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of discount actually applied to the line item.\n\nThe amount represents the amount of money applied as a line-item scoped discount.\nWhen an amount-based discount is scoped to the entire order, the value\nof `applied_money` is different than `amount_money` because the total\namount of the discount is distributed across all line items." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this discount. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "x-release-status": "BETA" }, "scope": { "$ref": "#/$defs/OrderLineItemDiscountScope", "description": "Indicates the level at which the discount applies. For `ORDER` scoped discounts,\nSquare generates references in `applied_discounts` on all order line items that do\nnot have them. For `LINE_ITEM` scoped discounts, the discount only applies to line items\nwith a discount reference in their `applied_discounts` field.\n\nThis field is immutable. To change the scope of a discount, you must delete\nthe discount and re-add it as a new discount.\nSee [OrderLineItemDiscountScope](#type-orderlineitemdiscountscope) for possible values" }, "reward_ids": { "type": "array", "items": { "type": "string" }, "description": "The reward IDs corresponding to this discount. The application and\nspecification of discounts that have `reward_ids` are completely controlled by the backing\ncriteria corresponding to the reward tiers of the rewards that are added to the order\nthrough the Loyalty API. To manually unapply discounts that are the result of added rewards,\nthe rewards must be removed from the order through the Loyalty API.", "readOnly": true, "x-release-status": "BETA" }, "pricing_rule_id": { "type": "string", "description": "The object ID of a [pricing rule](entity:CatalogPricingRule) to be applied\nautomatically to this discount. The specification and application of the discounts, to\nwhich a `pricing_rule_id` is assigned, are completely controlled by the corresponding\npricing rule.", "readOnly": true } } }, "OrderLineItemDiscountScope": { "type": "string", "enum": [ "OTHER_DISCOUNT_SCOPE", "LINE_ITEM", "ORDER" ], "x-enum-elements": [ { "name": "OTHER_DISCOUNT_SCOPE", "description": "Used for reporting only.\nThe original transaction discount scope is currently not supported by the API." }, { "name": "LINE_ITEM", "description": "The discount should be applied to only line items specified by\n`OrderLineItemAppliedDiscount` reference records." }, { "name": "ORDER", "description": "The discount should be applied to the entire order." } ], "description": "Indicates whether this is a line-item or order-level discount.", "x-release-status": "PUBLIC" }, "OrderLineItemDiscountType": { "type": "string", "enum": [ "UNKNOWN_DISCOUNT", "FIXED_PERCENTAGE", "FIXED_AMOUNT", "VARIABLE_PERCENTAGE", "VARIABLE_AMOUNT" ], "x-enum-elements": [ { "name": "UNKNOWN_DISCOUNT", "description": "Used for reporting only.\nThe original transaction discount type is currently not supported by the API." }, { "name": "FIXED_PERCENTAGE", "description": "Apply the discount as a fixed percentage (such as 5%) off the item price." }, { "name": "FIXED_AMOUNT", "description": "Apply the discount as a fixed monetary value (such as $1.00) off the item price." }, { "name": "VARIABLE_PERCENTAGE", "description": "Apply the discount as a variable percentage based on the item\nprice.\n\nThe specific discount percentage of a `VARIABLE_PERCENTAGE` discount\nis assigned at the time of the purchase." }, { "name": "VARIABLE_AMOUNT", "description": "Apply the discount as a variable amount based on the item price.\n\nThe specific discount amount of a `VARIABLE_AMOUNT` discount\nis assigned at the time of the purchase." } ], "description": "Indicates how the discount is applied to the associated line item or order.", "x-release-status": "PUBLIC" }, "OrderLineItemItemType": { "type": "string", "enum": [ "ITEM", "CUSTOM_AMOUNT", "GIFT_CARD" ], "x-enum-elements": [ { "name": "ITEM", "description": "Indicates that the line item is an itemized sale." }, { "name": "CUSTOM_AMOUNT", "description": "Indicates that the line item is a non-itemized sale." }, { "name": "GIFT_CARD", "description": "Indicates that the line item is a gift card sale. Gift cards sold through\nthe Orders API are sold in an unactivated state and can be activated through the\nGift Cards API using the line item `uid`." } ], "description": "Represents the line item type.", "x-release-status": "BETA" }, "OrderLineItemModifier": { "type": "object", "description": "A [CatalogModifier](entity:CatalogModifier).", "x-release-status": "PUBLIC", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the modifier only within this order.", "maxLength": 60, "x-release-status": "BETA" }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing [CatalogModifier](entity:CatalogModifier).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this modifier references.", "format": "int64" }, "name": { "type": [ "string", "null" ], "description": "The name of the item modifier.", "maxLength": 255 }, "quantity": { "type": [ "string", "null" ], "description": "The quantity of the line item modifier. The modifier quantity can be 0 or more.\nFor example, suppose a restaurant offers a cheeseburger on the menu. When a buyer orders\nthis item, the restaurant records the purchase by creating an `Order` object with a line item\nfor a burger. The line item includes a line item modifier: the name is cheese and the quantity\nis 1. The buyer has the option to order extra cheese (or no cheese). If the buyer chooses\nthe extra cheese option, the modifier quantity increases to 2. If the buyer does not want\nany cheese, the modifier quantity is set to 0." }, "base_price_money": { "$ref": "#/$defs/Money", "description": "The base price for the modifier.\n\n`base_price_money` is required for ad hoc modifiers.\nIf both `catalog_object_id` and `base_price_money` are set, `base_price_money` will\noverride the predefined [CatalogModifier](entity:CatalogModifier) price." }, "total_price_money": { "$ref": "#/$defs/Money", "description": "The total price of the item modifier for its line item.\nThis is the modifier's `base_price_money` multiplied by the line item's quantity.", "readOnly": true }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this order. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "x-release-status": "BETA" } } }, "OrderLineItemPricingBlocklists": { "type": "object", "description": "Describes pricing adjustments that are blocked from automatic\napplication to a line item. For more information, see\n[Apply Taxes and Discounts](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts).", "x-release-status": "BETA", "properties": { "blocked_discounts": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemPricingBlocklistsBlockedDiscount" }, "description": "A list of discounts blocked from applying to the line item.\nDiscounts can be blocked by the `discount_uid` (for ad hoc discounts) or\nthe `discount_catalog_object_id` (for catalog discounts)." }, "blocked_taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemPricingBlocklistsBlockedTax" }, "description": "A list of taxes blocked from applying to the line item.\nTaxes can be blocked by the `tax_uid` (for ad hoc taxes) or\nthe `tax_catalog_object_id` (for catalog taxes)." } } }, "OrderLineItemPricingBlocklistsBlockedDiscount": { "type": "object", "description": "A discount to block from applying to a line item. The discount must be\nidentified by either `discount_uid` or `discount_catalog_object_id`, but not both.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID of the `BlockedDiscount` within the order.", "maxLength": 60 }, "discount_uid": { "type": [ "string", "null" ], "description": "The `uid` of the discount that should be blocked. Use this field to block\nad hoc discounts. For catalog discounts, use the `discount_catalog_object_id` field.", "maxLength": 60 }, "discount_catalog_object_id": { "type": [ "string", "null" ], "description": "The `catalog_object_id` of the discount that should be blocked.\nUse this field to block catalog discounts. For ad hoc discounts, use the\n`discount_uid` field.", "maxLength": 192 } } }, "OrderLineItemPricingBlocklistsBlockedTax": { "type": "object", "description": "A tax to block from applying to a line item. The tax must be\nidentified by either `tax_uid` or `tax_catalog_object_id`, but not both.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID of the `BlockedTax` within the order.", "maxLength": 60 }, "tax_uid": { "type": [ "string", "null" ], "description": "The `uid` of the tax that should be blocked. Use this field to block\nad hoc taxes. For catalog, taxes use the `tax_catalog_object_id` field.", "maxLength": 60 }, "tax_catalog_object_id": { "type": [ "string", "null" ], "description": "The `catalog_object_id` of the tax that should be blocked.\nUse this field to block catalog taxes. For ad hoc taxes, use the\n`tax_uid` field.", "maxLength": 192 } } }, "OrderLineItemTax": { "type": "object", "description": "Represents a tax that applies to one or more line item in the order.\n\nFixed-amount, order-scoped taxes are distributed across all non-zero line item totals.\nThe amount distributed to each line item is relative to the amount the item\ncontributes to the order subtotal.", "x-release-status": "PUBLIC", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the tax only within this order.", "maxLength": 60, "x-release-status": "BETA" }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing [CatalogTax](entity:CatalogTax).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this tax references.", "format": "int64" }, "name": { "type": [ "string", "null" ], "description": "The tax's name.", "maxLength": 255 }, "type": { "$ref": "#/$defs/OrderLineItemTaxType", "description": "Indicates the calculation method used to apply the tax.\nSee [OrderLineItemTaxType](#type-orderlineitemtaxtype) for possible values" }, "percentage": { "type": [ "string", "null" ], "description": "The percentage of the tax, as a string representation of a decimal\nnumber. For example, a value of `\"7.25\"` corresponds to a percentage of\n7.25%.", "maxLength": 10 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this tax. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "x-release-status": "BETA" }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of money applied to the order by the tax.\n\n- For percentage-based taxes, `applied_money` is the money\ncalculated using the percentage." }, "scope": { "$ref": "#/$defs/OrderLineItemTaxScope", "description": "Indicates the level at which the tax applies. For `ORDER` scoped taxes,\nSquare generates references in `applied_taxes` on all order line items that do\nnot have them. For `LINE_ITEM` scoped taxes, the tax only applies to line items\nwith references in their `applied_taxes` field.\n\nThis field is immutable. To change the scope, you must delete the tax and\nre-add it as a new tax.\nSee [OrderLineItemTaxScope](#type-orderlineitemtaxscope) for possible values" }, "auto_applied": { "type": "boolean", "description": "Determines whether the tax was automatically applied to the order based on\nthe catalog configuration. For an example, see\n[Automatically Apply Taxes to an Order](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts/auto-apply-taxes).", "readOnly": true, "x-release-status": "BETA" } } }, "OrderLineItemTaxScope": { "type": "string", "enum": [ "OTHER_TAX_SCOPE", "LINE_ITEM", "ORDER" ], "x-enum-elements": [ { "name": "OTHER_TAX_SCOPE", "description": "Used for reporting only.\nThe original transaction tax scope is currently not supported by the API." }, { "name": "LINE_ITEM", "description": "The tax should be applied only to line items specified by\nthe `OrderLineItemAppliedTax` reference records." }, { "name": "ORDER", "description": "The tax should be applied to the entire order." } ], "description": "Indicates whether this is a line-item or order-level tax.", "x-release-status": "PUBLIC" }, "OrderLineItemTaxType": { "type": "string", "enum": [ "UNKNOWN_TAX", "ADDITIVE", "INCLUSIVE" ], "x-enum-elements": [ { "name": "UNKNOWN_TAX", "description": "Used for reporting only.\nThe original transaction tax type is currently not supported by the API." }, { "name": "ADDITIVE", "description": "The tax is an additive tax. The tax amount is added on top of the price.\nFor example, an item with a cost of 1.00 USD and a 10% additive tax has a total\ncost to the buyer of 1.10 USD." }, { "name": "INCLUSIVE", "description": "The tax is an inclusive tax. Inclusive taxes are already included\nin the line item price or order total. For example, an item with a cost of\n1.00 USD and a 10% inclusive tax has a pretax cost of 0.91 USD\n(91 cents) and a 0.09 (9 cents) tax for a total cost of 1.00 USD to\nthe buyer." } ], "description": "Indicates how the tax is applied to the associated line item or order.", "x-release-status": "PUBLIC" }, "OrderMoneyAmounts": { "type": "object", "description": "A collection of various money amounts.", "x-release-status": "BETA", "properties": { "total_money": { "$ref": "#/$defs/Money", "description": "The total money." }, "tax_money": { "$ref": "#/$defs/Money", "description": "The money associated with taxes." }, "discount_money": { "$ref": "#/$defs/Money", "description": "The money associated with discounts." }, "tip_money": { "$ref": "#/$defs/Money", "description": "The money associated with tips." }, "service_charge_money": { "$ref": "#/$defs/Money", "description": "The money associated with service charges." } } }, "OrderPricingOptions": { "type": "object", "description": "Pricing options for an order. The options affect how the order's price is calculated.\nThey can be used, for example, to apply automatic price adjustments that are based on preconfigured\n[pricing rules](entity:CatalogPricingRule).", "x-release-status": "PUBLIC", "properties": { "auto_apply_discounts": { "type": [ "boolean", "null" ], "description": "The option to determine whether pricing rule-based\ndiscounts are automatically applied to an order." }, "auto_apply_taxes": { "type": [ "boolean", "null" ], "description": "The option to determine whether rule-based taxes are automatically\napplied to an order when the criteria of the corresponding rules are met.", "x-release-status": "BETA" } } }, "OrderQuantityUnit": { "type": "object", "description": "Contains the measurement unit for a quantity and a precision that\nspecifies the number of digits after the decimal point for decimal quantities.", "x-release-status": "PUBLIC", "properties": { "measurement_unit": { "$ref": "#/$defs/MeasurementUnit", "description": "A [MeasurementUnit](entity:MeasurementUnit) that represents the\nunit of measure for the quantity." }, "precision": { "type": [ "integer", "null" ], "description": "For non-integer quantities, represents the number of digits after the decimal point that are\nrecorded for this quantity.\n\nFor example, a precision of 1 allows quantities such as `\"1.0\"` and `\"1.1\"`, but not `\"1.01\"`.\n\nMin: 0. Max: 5." }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing the\n[CatalogMeasurementUnit](entity:CatalogMeasurementUnit).\n\nThis field is set when this is a catalog-backed measurement unit." }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this measurement unit references.\n\nThis field is set when this is a catalog-backed measurement unit.", "format": "int64" } } }, "OrderReturn": { "type": "object", "description": "The set of line items, service charges, taxes, discounts, tips, and other items being returned in an order.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the return only within this order.", "maxLength": 60 }, "source_order_id": { "type": [ "string", "null" ], "description": "An order that contains the original sale of these return line items. This is unset\nfor unlinked returns." }, "return_line_items": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderReturnLineItem" }, "description": "A collection of line items that are being returned." }, "return_service_charges": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderReturnServiceCharge" }, "description": "A collection of service charges that are being returned." }, "return_taxes": { "type": "array", "items": { "$ref": "#/$defs/OrderReturnTax" }, "description": "A collection of references to taxes being returned for an order, including the total\napplied tax amount to be returned. The taxes must reference a top-level tax ID from the source\norder.", "readOnly": true }, "return_discounts": { "type": "array", "items": { "$ref": "#/$defs/OrderReturnDiscount" }, "description": "A collection of references to discounts being returned for an order, including the total\napplied discount amount to be returned. The discounts must reference a top-level discount ID\nfrom the source order.", "readOnly": true }, "return_tips": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderReturnTip" }, "description": "A collection of references to tips being returned for an order." }, "rounding_adjustment": { "$ref": "#/$defs/OrderRoundingAdjustment", "description": "A positive or negative rounding adjustment to the total value being returned. Adjustments are commonly\nused to apply cash rounding when the minimum unit of the account is smaller than the lowest\nphysical denomination of the currency." }, "return_amounts": { "$ref": "#/$defs/OrderMoneyAmounts", "description": "An aggregate monetary value being returned by this return entry." } } }, "OrderReturnDiscount": { "type": "object", "description": "Represents a discount being returned that applies to one or more return line items in an\norder.\n\nFixed-amount, order-scoped discounts are distributed across all non-zero return line item totals.\nThe amount distributed to each return line item is relative to that item’s contribution to the\norder subtotal.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the returned discount only within this order.", "maxLength": 60 }, "source_discount_uid": { "type": [ "string", "null" ], "description": "The discount `uid` from the order that contains the original application of this discount.", "maxLength": 60 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing [CatalogDiscount](entity:CatalogDiscount).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this discount references.", "format": "int64" }, "name": { "type": [ "string", "null" ], "description": "The discount's name.", "maxLength": 255 }, "type": { "$ref": "#/$defs/OrderLineItemDiscountType", "description": "The type of the discount. If it is created by the API, it is `FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\n\nDiscounts that do not reference a catalog object ID must have a type of\n`FIXED_PERCENTAGE` or `FIXED_AMOUNT`.\nSee [OrderLineItemDiscountType](#type-orderlineitemdiscounttype) for possible values" }, "percentage": { "type": [ "string", "null" ], "description": "The percentage of the tax, as a string representation of a decimal number.\nA value of `\"7.25\"` corresponds to a percentage of 7.25%.\n\n`percentage` is not set for amount-based discounts.", "maxLength": 10 }, "amount_money": { "$ref": "#/$defs/Money", "description": "The total declared monetary amount of the discount.\n\n`amount_money` is not set for percentage-based discounts." }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of discount actually applied to this line item. When an amount-based\ndiscount is at the order level, this value is different from `amount_money` because the discount\nis distributed across the line items.", "readOnly": true }, "scope": { "$ref": "#/$defs/OrderLineItemDiscountScope", "description": "Indicates the level at which the `OrderReturnDiscount` applies. For `ORDER` scoped\ndiscounts, the server generates references in `applied_discounts` on all\n`OrderReturnLineItem`s. For `LINE_ITEM` scoped discounts, the discount is only applied to\n`OrderReturnLineItem`s with references in their `applied_discounts` field.\nSee [OrderLineItemDiscountScope](#type-orderlineitemdiscountscope) for possible values" } } }, "OrderReturnLineItem": { "type": "object", "description": "The line item being returned in an order.", "x-release-status": "BETA", "required": [ "quantity" ], "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID for this return line-item entry.", "maxLength": 60 }, "source_line_item_uid": { "type": [ "string", "null" ], "description": "The `uid` of the line item in the original sale order.", "maxLength": 60 }, "name": { "type": [ "string", "null" ], "description": "The name of the line item.", "maxLength": 512 }, "quantity": { "type": "string", "description": "The quantity returned, formatted as a decimal number.\nFor example, `\"3\"`.\n\nLine items with a `quantity_unit` can have non-integer quantities.\nFor example, `\"1.70000\"`.", "minLength": 1, "maxLength": 12 }, "quantity_unit": { "$ref": "#/$defs/OrderQuantityUnit", "description": "The unit and precision that this return line item's quantity is measured in." }, "note": { "type": [ "string", "null" ], "description": "The note of the return line item.", "maxLength": 2000 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The [CatalogItemVariation](entity:CatalogItemVariation) ID applied to this return line item.", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this line item references.", "format": "int64" }, "variation_name": { "type": [ "string", "null" ], "description": "The name of the variation applied to this return line item.", "maxLength": 400 }, "item_type": { "$ref": "#/$defs/OrderLineItemItemType", "description": "The type of line item: an itemized return, a non-itemized return (custom amount),\nor the return of an unactivated gift card sale.\nSee [OrderLineItemItemType](#type-orderlineitemitemtype) for possible values" }, "return_modifiers": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderReturnLineItemModifier" }, "description": "The [CatalogModifier](entity:CatalogModifier)s applied to this line item." }, "applied_taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedTax" }, "description": "The list of references to `OrderReturnTax` entities applied to the return line item. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level\n`OrderReturnTax` applied to the return line item. On reads, the applied amount\nis populated." }, "applied_discounts": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedDiscount" }, "description": "The list of references to `OrderReturnDiscount` entities applied to the return line item. Each\n`OrderLineItemAppliedDiscount` has a `discount_uid` that references the `uid` of a top-level\n`OrderReturnDiscount` applied to the return line item. On reads, the applied amount\nis populated." }, "base_price_money": { "$ref": "#/$defs/Money", "description": "The base price for a single unit of the line item." }, "variation_total_price_money": { "$ref": "#/$defs/Money", "description": "The total price of all item variations returned in this line item.\nThe price is calculated as `base_price_money` multiplied by `quantity` and\ndoes not include modifiers.", "readOnly": true }, "gross_return_money": { "$ref": "#/$defs/Money", "description": "The gross return amount of money calculated as (item base price + modifiers price) * quantity.", "readOnly": true }, "total_tax_money": { "$ref": "#/$defs/Money", "description": "The total amount of tax money to return for the line item.", "readOnly": true }, "total_discount_money": { "$ref": "#/$defs/Money", "description": "The total amount of discount money to return for the line item.", "readOnly": true }, "total_money": { "$ref": "#/$defs/Money", "description": "The total amount of money to return for this line item.", "readOnly": true }, "applied_service_charges": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedServiceCharge" }, "description": "The list of references to `OrderReturnServiceCharge` entities applied to the return\nline item. Each `OrderLineItemAppliedServiceCharge` has a `service_charge_uid` that\nreferences the `uid` of a top-level `OrderReturnServiceCharge` applied to the return line\nitem. On reads, the applied amount is populated." }, "total_service_charge_money": { "$ref": "#/$defs/Money", "description": "The total amount of apportioned service charge money to return for the line item.", "readOnly": true } } }, "OrderReturnLineItemModifier": { "type": "object", "description": "A line item modifier being returned.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the return modifier only within this order.", "maxLength": 60 }, "source_modifier_uid": { "type": [ "string", "null" ], "description": "The modifier `uid` from the order's line item that contains the\noriginal sale of this line item modifier.", "maxLength": 60 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing [CatalogModifier](entity:CatalogModifier).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this line item modifier references.", "format": "int64" }, "name": { "type": [ "string", "null" ], "description": "The name of the item modifier.", "maxLength": 255 }, "base_price_money": { "$ref": "#/$defs/Money", "description": "The base price for the modifier.\n\n`base_price_money` is required for ad hoc modifiers.\nIf both `catalog_object_id` and `base_price_money` are set, `base_price_money` overrides the predefined [CatalogModifier](entity:CatalogModifier) price." }, "total_price_money": { "$ref": "#/$defs/Money", "description": "The total price of the item modifier for its line item.\nThis is the modifier's `base_price_money` multiplied by the line item's quantity.", "readOnly": true }, "quantity": { "type": [ "string", "null" ], "description": "The quantity of the line item modifier. The modifier quantity can be 0 or more.\nFor example, suppose a restaurant offers a cheeseburger on the menu. When a buyer orders\nthis item, the restaurant records the purchase by creating an `Order` object with a line item\nfor a burger. The line item includes a line item modifier: the name is cheese and the quantity\nis 1. The buyer has the option to order extra cheese (or no cheese). If the buyer chooses\nthe extra cheese option, the modifier quantity increases to 2. If the buyer does not want\nany cheese, the modifier quantity is set to 0." } } }, "OrderReturnServiceCharge": { "type": "object", "description": "Represents the service charge applied to the original order.", "x-release-status": "PUBLIC", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the return service charge only within this order.", "maxLength": 60, "x-release-status": "BETA" }, "source_service_charge_uid": { "type": [ "string", "null" ], "description": "The service charge `uid` from the order containing the original\nservice charge. `source_service_charge_uid` is `null` for\nunlinked returns.", "maxLength": 60 }, "name": { "type": [ "string", "null" ], "description": "The name of the service charge.", "maxLength": 255 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID of the associated [OrderServiceCharge](entity:OrderServiceCharge).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this service charge references.", "format": "int64" }, "percentage": { "type": [ "string", "null" ], "description": "The percentage of the service charge, as a string representation of\na decimal number. For example, a value of `\"7.25\"` corresponds to a\npercentage of 7.25%.\n\nEither `percentage` or `amount_money` should be set, but not both.", "maxLength": 10 }, "amount_money": { "$ref": "#/$defs/Money", "description": "The amount of a non-percentage-based service charge.\n\nEither `percentage` or `amount_money` should be set, but not both." }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of money applied to the order by the service charge, including\nany inclusive tax amounts, as calculated by Square.\n\n- For fixed-amount service charges, `applied_money` is equal to `amount_money`.\n- For percentage-based service charges, `applied_money` is the money calculated using the percentage.", "readOnly": true }, "total_money": { "$ref": "#/$defs/Money", "description": "The total amount of money to collect for the service charge.\n\n__NOTE__: If an inclusive tax is applied to the service charge, `total_money`\ndoes not equal `applied_money` plus `total_tax_money` because the inclusive\ntax amount is already included in both `applied_money` and `total_tax_money`.", "readOnly": true }, "total_tax_money": { "$ref": "#/$defs/Money", "description": "The total amount of tax money to collect for the service charge.", "readOnly": true }, "calculation_phase": { "$ref": "#/$defs/OrderServiceChargeCalculationPhase", "description": "The calculation phase after which to apply the service charge.\nSee [OrderServiceChargeCalculationPhase](#type-orderservicechargecalculationphase) for possible values", "readOnly": true }, "taxable": { "type": [ "boolean", "null" ], "description": "Indicates whether the surcharge can be taxed. Service charges\ncalculated in the `TOTAL_PHASE` cannot be marked as taxable." }, "applied_taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedTax" }, "description": "The list of references to `OrderReturnTax` entities applied to the\n`OrderReturnServiceCharge`. Each `OrderLineItemAppliedTax` has a `tax_uid`\nthat references the `uid` of a top-level `OrderReturnTax` that is being\napplied to the `OrderReturnServiceCharge`. On reads, the applied amount is\npopulated.", "x-release-status": "BETA" }, "treatment_type": { "$ref": "#/$defs/OrderServiceChargeTreatmentType", "description": "The treatment type of the service charge.\nSee [OrderServiceChargeTreatmentType](#type-orderservicechargetreatmenttype) for possible values", "x-release-status": "BETA" }, "scope": { "$ref": "#/$defs/OrderServiceChargeScope", "description": "Indicates the level at which the apportioned service charge applies. For `ORDER`\nscoped service charges, Square generates references in `applied_service_charges` on\nall order line items that do not have them. For `LINE_ITEM` scoped service charges,\nthe service charge only applies to line items with a service charge reference in their\n`applied_service_charges` field.\n\nThis field is immutable. To change the scope of an apportioned service charge, you must delete\nthe apportioned service charge and re-add it as a new apportioned service charge.\nSee [OrderServiceChargeScope](#type-orderservicechargescope) for possible values", "x-release-status": "BETA" } } }, "OrderReturnTax": { "type": "object", "description": "Represents a tax being returned that applies to one or more return line items in an order.\n\nFixed-amount, order-scoped taxes are distributed across all non-zero return line item totals.\nThe amount distributed to each return line item is relative to that item’s contribution to the\norder subtotal.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the returned tax only within this order.", "maxLength": 60 }, "source_tax_uid": { "type": [ "string", "null" ], "description": "The tax `uid` from the order that contains the original tax charge.", "maxLength": 60 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing [CatalogTax](entity:CatalogTax).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this tax references.", "format": "int64" }, "name": { "type": [ "string", "null" ], "description": "The tax's name.", "maxLength": 255 }, "type": { "$ref": "#/$defs/OrderLineItemTaxType", "description": "Indicates the calculation method used to apply the tax.\nSee [OrderLineItemTaxType](#type-orderlineitemtaxtype) for possible values" }, "percentage": { "type": [ "string", "null" ], "description": "The percentage of the tax, as a string representation of a decimal number.\nFor example, a value of `\"7.25\"` corresponds to a percentage of 7.25%.", "maxLength": 10 }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of money applied by the tax in an order.", "readOnly": true }, "scope": { "$ref": "#/$defs/OrderLineItemTaxScope", "description": "Indicates the level at which the `OrderReturnTax` applies. For `ORDER` scoped\ntaxes, Square generates references in `applied_taxes` on all\n`OrderReturnLineItem`s. For `LINE_ITEM` scoped taxes, the tax is only applied to\n`OrderReturnLineItem`s with references in their `applied_discounts` field.\nSee [OrderLineItemTaxScope](#type-orderlineitemtaxscope) for possible values" } } }, "OrderReturnTip": { "type": "object", "description": "A tip being returned.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the tip only within this order.", "maxLength": 60 }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of tip being returned\n--", "readOnly": true }, "source_tender_uid": { "type": [ "string", "null" ], "description": "The tender `uid` from the order that contains the original application of this tip.", "maxLength": 192 }, "source_tender_id": { "type": [ "string", "null" ], "description": "The tender `id` from the order that contains the original application of this tip.", "maxLength": 192 } } }, "OrderReward": { "type": "object", "description": "Represents a reward that can be applied to an order if the necessary\nreward tier criteria are met. Rewards are created through the Loyalty API.", "x-release-status": "BETA", "required": [ "id", "reward_tier_id" ], "properties": { "id": { "type": "string", "description": "The identifier of the reward.", "minLength": 1 }, "reward_tier_id": { "type": "string", "description": "The identifier of the reward tier corresponding to this reward.", "minLength": 1 } } }, "OrderRoundingAdjustment": { "type": "object", "description": "A rounding adjustment of the money being returned. Commonly used to apply cash rounding\nwhen the minimum unit of the account is smaller than the lowest physical denomination of the currency.", "x-release-status": "BETA", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the rounding adjustment only within this order.", "maxLength": 60 }, "name": { "type": [ "string", "null" ], "description": "The name of the rounding adjustment from the original sale order." }, "amount_money": { "$ref": "#/$defs/Money", "description": "The actual rounding adjustment amount." } } }, "OrderServiceCharge": { "type": "object", "description": "Represents a service charge applied to an order.", "x-release-status": "PUBLIC", "properties": { "uid": { "type": [ "string", "null" ], "description": "A unique ID that identifies the service charge only within this order.", "maxLength": 60, "x-release-status": "BETA" }, "name": { "type": [ "string", "null" ], "description": "The name of the service charge.", "maxLength": 512 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The catalog object ID referencing the service charge [CatalogObject](entity:CatalogObject).", "maxLength": 192 }, "catalog_version": { "type": [ "integer", "null" ], "description": "The version of the catalog object that this service charge references.", "format": "int64" }, "percentage": { "type": [ "string", "null" ], "description": "The service charge percentage as a string representation of a\ndecimal number. For example, `\"7.25\"` indicates a service charge of 7.25%.\n\nExactly 1 of `percentage` or `amount_money` should be set.", "maxLength": 10 }, "amount_money": { "$ref": "#/$defs/Money", "description": "The amount of a non-percentage-based service charge.\n\nExactly one of `percentage` or `amount_money` should be set." }, "applied_money": { "$ref": "#/$defs/Money", "description": "The amount of money applied to the order by the service charge,\nincluding any inclusive tax amounts, as calculated by Square.\n\n- For fixed-amount service charges, `applied_money` is equal to `amount_money`.\n- For percentage-based service charges, `applied_money` is the money\ncalculated using the percentage.", "readOnly": true }, "total_money": { "$ref": "#/$defs/Money", "description": "The total amount of money to collect for the service charge.\n\n__Note__: If an inclusive tax is applied to the service charge,\n`total_money` does not equal `applied_money` plus `total_tax_money`\nbecause the inclusive tax amount is already included in both\n`applied_money` and `total_tax_money`.", "readOnly": true }, "total_tax_money": { "$ref": "#/$defs/Money", "description": "The total amount of tax money to collect for the service charge.", "readOnly": true }, "calculation_phase": { "$ref": "#/$defs/OrderServiceChargeCalculationPhase", "description": "The calculation phase at which to apply the service charge.\nSee [OrderServiceChargeCalculationPhase](#type-orderservicechargecalculationphase) for possible values" }, "taxable": { "type": [ "boolean", "null" ], "description": "Indicates whether the service charge can be taxed. If set to `true`,\norder-level taxes automatically apply to the service charge. Note that\nservice charges calculated in the `TOTAL_PHASE` cannot be marked as taxable." }, "applied_taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/OrderLineItemAppliedTax" }, "description": "The list of references to the taxes applied to this service charge. Each\n`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level\n`OrderLineItemTax` that is being applied to this service charge. On reads, the amount applied\nis populated.\n\nAn `OrderLineItemAppliedTax` is automatically created on every taxable service charge\nfor all `ORDER` scoped taxes that are added to the order. `OrderLineItemAppliedTax` records\nfor `LINE_ITEM` scoped taxes must be added in requests for the tax to apply to any taxable\nservice charge. Taxable service charges have the `taxable` field set to `true` and calculated\nin the `SUBTOTAL_PHASE`.\n\nTo change the amount of a tax, modify the referenced top-level tax.", "x-release-status": "BETA" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Application-defined data attached to this service charge. Metadata fields are intended\nto store descriptive references or associations with an entity in another system or store brief\ninformation about the object. Square does not process this field; it only stores and returns it\nin relevant API calls. Do not use metadata to store any sensitive information (such as personally\nidentifiable information or card details).\n\nKeys written by applications must be 60 characters or less and must be in the character set\n`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed\nwith a namespace, separated from the key with a ':' character.\n\nValues have a maximum length of 255 characters.\n\nAn application can have up to 10 entries per metadata field.\n\nEntries written by applications are private and can only be read or modified by the same\napplication.\n\nFor more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata).", "x-release-status": "BETA" }, "type": { "$ref": "#/$defs/OrderServiceChargeType", "description": "The type of the service charge.\nSee [OrderServiceChargeType](#type-orderservicechargetype) for possible values", "readOnly": true }, "treatment_type": { "$ref": "#/$defs/OrderServiceChargeTreatmentType", "description": "The treatment type of the service charge.\nSee [OrderServiceChargeTreatmentType](#type-orderservicechargetreatmenttype) for possible values", "x-release-status": "BETA" }, "scope": { "$ref": "#/$defs/OrderServiceChargeScope", "description": "Indicates the level at which the apportioned service charge applies. For `ORDER`\nscoped service charges, Square generates references in `applied_service_charges` on\nall order line items that do not have them. For `LINE_ITEM` scoped service charges,\nthe service charge only applies to line items with a service charge reference in their\n`applied_service_charges` field.\n\nThis field is immutable. To change the scope of an apportioned service charge, you must delete\nthe apportioned service charge and re-add it as a new apportioned service charge.\nSee [OrderServiceChargeScope](#type-orderservicechargescope) for possible values", "x-release-status": "BETA" } } }, "OrderServiceChargeCalculationPhase": { "type": "string", "enum": [ "SUBTOTAL_PHASE", "TOTAL_PHASE", "APPORTIONED_PERCENTAGE_PHASE", "APPORTIONED_AMOUNT_PHASE" ], "x-enum-elements": [ { "name": "SUBTOTAL_PHASE", "description": "The service charge is applied after discounts, but before\ntaxes." }, { "name": "TOTAL_PHASE", "description": "The service charge is applied after all discounts and taxes\nare applied." }, { "name": "APPORTIONED_PERCENTAGE_PHASE", "description": "The service charge is calculated as a compounding adjustment\nafter any discounts, but before amount based apportioned service charges\nand any tax considerations." }, { "name": "APPORTIONED_AMOUNT_PHASE", "description": "The service charge is calculated as a compounding adjustment\nafter any discounts and percentage based apportioned service charges,\nbut before any tax considerations." } ], "description": "Represents a phase in the process of calculating order totals.\nService charges are applied after the indicated phase.\n\n[Read more about how order totals are calculated.](https://developer.squareup.com/docs/orders-api/how-it-works#how-totals-are-calculated)", "x-release-status": "PUBLIC" }, "OrderServiceChargeScope": { "type": "string", "enum": [ "OTHER_SERVICE_CHARGE_SCOPE", "LINE_ITEM", "ORDER" ], "x-enum-elements": [ { "name": "OTHER_SERVICE_CHARGE_SCOPE", "description": "Used for reporting only.\nThe original transaction service charge scope is currently not supported by the API." }, { "name": "LINE_ITEM", "description": "The service charge should be applied to only line items specified by\n`OrderLineItemAppliedServiceCharge` reference records." }, { "name": "ORDER", "description": "The service charge should be applied to the entire order." } ], "description": "Indicates whether this is a line-item or order-level apportioned\nservice charge.", "x-release-status": "BETA" }, "OrderServiceChargeTreatmentType": { "type": "string", "enum": [ "LINE_ITEM_TREATMENT", "APPORTIONED_TREATMENT" ], "x-enum-elements": [ { "name": "LINE_ITEM_TREATMENT", "description": "" }, { "name": "APPORTIONED_TREATMENT", "description": "" } ], "description": "Indicates whether the service charge will be treated as a value-holding line item or\napportioned toward a line item.", "x-release-status": "BETA" }, "OrderServiceChargeType": { "type": "string", "enum": [ "AUTO_GRATUITY", "CUSTOM" ], "x-enum-elements": [ { "name": "AUTO_GRATUITY", "description": "" }, { "name": "CUSTOM", "description": "" } ], "x-release-status": "PUBLIC" }, "OrderSource": { "type": "object", "description": "Represents the origination details of an order.", "x-release-status": "PUBLIC", "properties": { "name": { "type": [ "string", "null" ], "description": "The name used to identify the place (physical or digital) that an order originates.\nIf unset, the name defaults to the name of the application that created the order." } } }, "OrderState": { "type": "string", "enum": [ "OPEN", "COMPLETED", "CANCELED", "DRAFT" ], "x-enum-elements": [ { "name": "OPEN", "description": "Indicates that the order is open. Open orders can be updated." }, { "name": "COMPLETED", "description": "Indicates that the order is completed. Completed orders are fully paid. This is a terminal state." }, { "name": "CANCELED", "description": "Indicates that the order is canceled. Canceled orders are not paid. This is a terminal state." }, { "name": "DRAFT", "description": "Indicates that the order is in a draft state. Draft orders can be updated,\nbut cannot be paid or fulfilled.\nFor more information, see [Create Orders](https://developer.squareup.com/docs/orders-api/create-orders)." } ], "description": "The state of the order.", "x-release-status": "PUBLIC" }, "PaymentLink": { "type": "object", "x-release-status": "PUBLIC", "required": [ "version" ], "properties": { "id": { "type": "string", "description": "The Square-assigned ID of the payment link.", "readOnly": true }, "version": { "type": "integer", "description": "The Square-assigned version number, which is incremented each time an update is committed to the payment link.", "maximum": 65535 }, "description": { "type": [ "string", "null" ], "description": "The optional description of the `payment_link` object.\nIt is primarily for use by your application and is not used anywhere.", "maxLength": 4096 }, "order_id": { "type": "string", "description": "The ID of the order associated with the payment link.", "maxLength": 192, "readOnly": true }, "checkout_options": { "$ref": "#/$defs/CheckoutOptions", "description": "The checkout options configured for the payment link.\nFor more information, see [Optional Checkout Configurations](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations)." }, "pre_populated_data": { "$ref": "#/$defs/PrePopulatedData", "description": "Describes buyer data to prepopulate\non the checkout page." }, "url": { "type": "string", "description": "The shortened URL of the payment link.", "maxLength": 255, "readOnly": true }, "long_url": { "type": "string", "description": "The long URL of the payment link.", "maxLength": 255, "readOnly": true }, "created_at": { "type": "string", "description": "The timestamp when the payment link was created, in RFC 3339 format." }, "updated_at": { "type": "string", "description": "The timestamp when the payment link was last updated, in RFC 3339 format." }, "payment_note": { "type": [ "string", "null" ], "description": "An optional note. After Square processes the payment, this note is added to the\nresulting `Payment`.", "maxLength": 500 } } }, "PaymentLinkRelatedResources": { "type": "object", "x-release-status": "PUBLIC", "properties": { "orders": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/Order" }, "description": "The order associated with the payment link." }, "subscription_plans": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CatalogObject" }, "description": "The subscription plan associated with the payment link." } } }, "PrePopulatedData": { "type": "object", "description": "Describes buyer data to prepopulate in the payment form.\nFor more information,\nsee [Optional Checkout Configurations](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations).", "x-release-status": "PUBLIC", "properties": { "buyer_email": { "type": [ "string", "null" ], "description": "The buyer email to prepopulate in the payment form.", "maxLength": 256 }, "buyer_phone_number": { "type": [ "string", "null" ], "description": "The buyer phone number to prepopulate in the payment form.", "maxLength": 17 }, "buyer_address": { "$ref": "#/$defs/Address", "description": "The buyer address to prepopulate in the payment form." } } }, "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" }, "Refund": { "type": "object", "description": "Represents a refund processed for a Square transaction.", "x-release-status": "PUBLIC", "required": [ "id", "location_id", "tender_id", "reason", "amount_money", "status" ], "properties": { "id": { "type": "string", "description": "The refund's unique ID.", "maxLength": 255 }, "location_id": { "type": "string", "description": "The ID of the refund's associated location.", "maxLength": 50 }, "transaction_id": { "type": [ "string", "null" ], "description": "The ID of the transaction that the refunded tender is part of.", "maxLength": 192 }, "tender_id": { "type": "string", "description": "The ID of the refunded tender.", "maxLength": 192 }, "created_at": { "type": "string", "description": "The timestamp for when the refund was created, in RFC 3339 format.", "maxLength": 32, "readOnly": true }, "reason": { "type": "string", "description": "The reason for the refund being issued.", "maxLength": 192 }, "amount_money": { "$ref": "#/$defs/Money", "description": "The amount of money refunded to the buyer." }, "status": { "$ref": "#/$defs/RefundStatus", "description": "The current status of the refund (`PENDING`, `APPROVED`, `REJECTED`,\nor `FAILED`).\nSee [RefundStatus](#type-refundstatus) for possible values" }, "processing_fee_money": { "$ref": "#/$defs/Money", "description": "The amount of Square processing fee money refunded to the *merchant*." }, "additional_recipients": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/AdditionalRecipient" }, "description": "Additional recipients (other than the merchant) receiving a portion of this refund.\nFor example, fees assessed on a refund of a purchase by a third party integration.", "x-release-status": "DEPRECATED" } } }, "RefundStatus": { "type": "string", "enum": [ "PENDING", "APPROVED", "REJECTED", "FAILED" ], "x-enum-elements": [ { "name": "PENDING", "description": "The refund is pending." }, { "name": "APPROVED", "description": "The refund has been approved by Square." }, { "name": "REJECTED", "description": "The refund has been rejected by Square." }, { "name": "FAILED", "description": "The refund failed." } ], "description": "Indicates a refund's current status.", "x-release-status": "PUBLIC" }, "ShippingFee": { "type": "object", "x-release-status": "PUBLIC", "required": [ "charge" ], "properties": { "name": { "type": [ "string", "null" ], "description": "The name for the shipping fee." }, "charge": { "$ref": "#/$defs/Money", "description": "The amount and currency for the shipping fee." } } }, "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" }, "Tender": { "type": "object", "description": "Represents a tender (i.e., a method of payment) used in a Square transaction.", "x-release-status": "PUBLIC", "required": [ "type" ], "properties": { "id": { "type": "string", "description": "The tender's unique ID. It is the associated payment ID.", "maxLength": 192 }, "location_id": { "type": [ "string", "null" ], "description": "The ID of the transaction's associated location.", "maxLength": 50 }, "transaction_id": { "type": [ "string", "null" ], "description": "The ID of the tender's associated transaction.", "maxLength": 192 }, "created_at": { "type": "string", "description": "The timestamp for when the tender was created, in RFC 3339 format.", "maxLength": 32, "readOnly": true }, "note": { "type": [ "string", "null" ], "description": "An optional note associated with the tender at the time of payment.", "maxLength": 500 }, "amount_money": { "$ref": "#/$defs/Money", "description": "The total amount of the tender, including `tip_money`. If the tender has a `payment_id`,\nthe `total_money` of the corresponding [Payment](entity:Payment) will be equal to the\n`amount_money` of the tender." }, "tip_money": { "$ref": "#/$defs/Money", "description": "The tip's amount of the tender." }, "processing_fee_money": { "$ref": "#/$defs/Money", "description": "The amount of any Square processing fees applied to the tender.\n\nThis field is not immediately populated when a new transaction is created.\nIt is usually available after about ten seconds." }, "customer_id": { "type": [ "string", "null" ], "description": "If the tender is associated with a customer or represents a customer's card on file,\nthis is the ID of the associated customer.", "maxLength": 191 }, "type": { "$ref": "#/$defs/TenderType", "description": "The type of tender, such as `CARD` or `CASH`.\nSee [TenderType](#type-tendertype) for possible values" }, "card_details": { "$ref": "#/$defs/TenderCardDetails", "description": "The details of the card tender.\n\nThis value is present only if the value of `type` is `CARD`." }, "cash_details": { "$ref": "#/$defs/TenderCashDetails", "description": "The details of the cash tender.\n\nThis value is present only if the value of `type` is `CASH`." }, "bank_account_details": { "$ref": "#/$defs/TenderBankAccountDetails", "description": "The details of the bank account tender.\n\nThis value is present only if the value of `type` is `BANK_ACCOUNT`." }, "buy_now_pay_later_details": { "$ref": "#/$defs/TenderBuyNowPayLaterDetails", "description": "The details of a Buy Now Pay Later tender.\n\nThis value is present only if the value of `type` is `BUY_NOW_PAY_LATER`." }, "square_account_details": { "$ref": "#/$defs/TenderSquareAccountDetails", "description": "The details of a Square Account tender.\n\nThis value is present only if the value of `type` is `SQUARE_ACCOUNT`." }, "additional_recipients": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/AdditionalRecipient" }, "description": "Additional recipients (other than the merchant) receiving a portion of this tender.\nFor example, fees assessed on the purchase by a third party integration.", "x-release-status": "DEPRECATED" }, "payment_id": { "type": [ "string", "null" ], "description": "The ID of the [Payment](entity:Payment) that corresponds to this tender.\nThis value is only present for payments created with the v2 Payments API.", "maxLength": 192 } } }, "TenderBankAccountDetails": { "type": "object", "description": "Represents the details of a tender with `type` `BANK_ACCOUNT`.\n\nSee [BankAccountPaymentDetails](entity:BankAccountPaymentDetails)\nfor more exposed details of a bank account payment.", "x-release-status": "PUBLIC", "properties": { "status": { "$ref": "#/$defs/TenderBankAccountDetailsStatus", "description": "The bank account payment's current state.\n\nSee [TenderBankAccountPaymentDetailsStatus](entity:TenderBankAccountDetailsStatus) for possible values.\nSee [TenderBankAccountDetailsStatus](#type-tenderbankaccountdetailsstatus) for possible values" } } }, "TenderBankAccountDetailsStatus": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED" ], "x-enum-elements": [ { "name": "PENDING", "description": "The bank account payment is in progress." }, { "name": "COMPLETED", "description": "The bank account payment has been completed." }, { "name": "FAILED", "description": "The bank account payment failed." } ], "description": "Indicates the bank account payment's current status.", "x-release-status": "PUBLIC" }, "TenderBuyNowPayLaterDetails": { "type": "object", "description": "Represents the details of a tender with `type` `BUY_NOW_PAY_LATER`.", "x-release-status": "PUBLIC", "properties": { "buy_now_pay_later_brand": { "$ref": "#/$defs/TenderBuyNowPayLaterDetailsBrand", "description": "The Buy Now Pay Later brand.\nSee [Brand](#type-brand) for possible values", "readOnly": true }, "status": { "$ref": "#/$defs/TenderBuyNowPayLaterDetailsStatus", "description": "The buy now pay later payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderBuyNowPayLaterDetailsStatus](entity:TenderBuyNowPayLaterDetailsStatus)\nfor possible values.\nSee [Status](#type-status) for possible values" } } }, "TenderBuyNowPayLaterDetailsBrand": { "type": "string", "enum": [ "OTHER_BRAND", "AFTERPAY" ], "x-enum-elements": [ { "name": "OTHER_BRAND", "description": "" }, { "name": "AFTERPAY", "description": "" } ], "x-release-status": "PUBLIC" }, "TenderBuyNowPayLaterDetailsStatus": { "type": "string", "enum": [ "AUTHORIZED", "CAPTURED", "VOIDED", "FAILED" ], "x-enum-elements": [ { "name": "AUTHORIZED", "description": "The buy now pay later payment has been authorized but not yet captured." }, { "name": "CAPTURED", "description": "The buy now pay later payment was authorized and subsequently captured (i.e., completed)." }, { "name": "VOIDED", "description": "The buy now pay later payment was authorized and subsequently voided (i.e., canceled)." }, { "name": "FAILED", "description": "The buy now pay later payment failed." } ], "x-release-status": "PUBLIC" }, "TenderCardDetails": { "type": "object", "description": "Represents additional details of a tender with `type` `CARD` or `SQUARE_GIFT_CARD`", "x-release-status": "PUBLIC", "properties": { "status": { "$ref": "#/$defs/TenderCardDetailsStatus", "description": "The credit card payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderCardDetailsStatus](entity:TenderCardDetailsStatus)\nfor possible values.\nSee [TenderCardDetailsStatus](#type-tendercarddetailsstatus) for possible values" }, "card": { "$ref": "#/$defs/Card", "description": "The credit card's non-confidential details." }, "entry_method": { "$ref": "#/$defs/TenderCardDetailsEntryMethod", "description": "The method used to enter the card's details for the transaction.\nSee [TenderCardDetailsEntryMethod](#type-tendercarddetailsentrymethod) for possible values" } } }, "TenderCardDetailsEntryMethod": { "type": "string", "enum": [ "SWIPED", "KEYED", "EMV", "ON_FILE", "CONTACTLESS" ], "x-enum-elements": [ { "name": "SWIPED", "description": "The card was swiped through a Square reader or Square stand." }, { "name": "KEYED", "description": "The card information was keyed manually into Square Point of Sale or a\nSquare-hosted web form." }, { "name": "EMV", "description": "The card was processed via EMV with a Square reader." }, { "name": "ON_FILE", "description": "The buyer's card details were already on file with Square." }, { "name": "CONTACTLESS", "description": "The card was processed via a contactless (i.e., NFC) transaction\nwith a Square reader." } ], "description": "Indicates the method used to enter the card's details.", "x-release-status": "PUBLIC" }, "TenderCardDetailsStatus": { "type": "string", "enum": [ "AUTHORIZED", "CAPTURED", "VOIDED", "FAILED" ], "x-enum-elements": [ { "name": "AUTHORIZED", "description": "The card transaction has been authorized but not yet captured." }, { "name": "CAPTURED", "description": "The card transaction was authorized and subsequently captured (i.e., completed)." }, { "name": "VOIDED", "description": "The card transaction was authorized and subsequently voided (i.e., canceled)." }, { "name": "FAILED", "description": "The card transaction failed." } ], "description": "Indicates the card transaction's current status.", "x-release-status": "PUBLIC" }, "TenderCashDetails": { "type": "object", "description": "Represents the details of a tender with `type` `CASH`.", "x-release-status": "PUBLIC", "properties": { "buyer_tendered_money": { "$ref": "#/$defs/Money", "description": "The total amount of cash provided by the buyer, before change is given." }, "change_back_money": { "$ref": "#/$defs/Money", "description": "The amount of change returned to the buyer." } } }, "TenderSquareAccountDetails": { "type": "object", "description": "Represents the details of a tender with `type` `SQUARE_ACCOUNT`.", "x-release-status": "PUBLIC", "properties": { "status": { "$ref": "#/$defs/TenderSquareAccountDetailsStatus", "description": "The Square Account payment's current state (such as `AUTHORIZED` or\n`CAPTURED`). See [TenderSquareAccountDetailsStatus](entity:TenderSquareAccountDetailsStatus)\nfor possible values.\nSee [Status](#type-status) for possible values" } } }, "TenderSquareAccountDetailsStatus": { "type": "string", "enum": [ "AUTHORIZED", "CAPTURED", "VOIDED", "FAILED" ], "x-enum-elements": [ { "name": "AUTHORIZED", "description": "The Square Account payment has been authorized but not yet captured." }, { "name": "CAPTURED", "description": "The Square Account payment was authorized and subsequently captured (i.e., completed)." }, { "name": "VOIDED", "description": "The Square Account payment was authorized and subsequently voided (i.e., canceled)." }, { "name": "FAILED", "description": "The Square Account payment failed." } ], "x-release-status": "PUBLIC" }, "TenderType": { "type": "string", "enum": [ "CARD", "CASH", "THIRD_PARTY_CARD", "SQUARE_GIFT_CARD", "NO_SALE", "BANK_ACCOUNT", "WALLET", "BUY_NOW_PAY_LATER", "SQUARE_ACCOUNT", "OTHER" ], "x-enum-elements": [ { "name": "CARD", "description": "A credit card." }, { "name": "CASH", "description": "Cash." }, { "name": "THIRD_PARTY_CARD", "description": "A credit card processed with a card processor other than Square.\n\nThis value applies only to merchants in countries where Square does not\nyet provide card processing." }, { "name": "SQUARE_GIFT_CARD", "description": "A Square gift card." }, { "name": "NO_SALE", "description": "This tender represents the register being opened for a \"no sale\" event." }, { "name": "BANK_ACCOUNT", "description": "A bank account payment." }, { "name": "WALLET", "description": "A payment from a digital wallet, e.g. Cash App, Paypay, Rakuten Pay,\nAu Pay, D Barai, Merpay, Wechat Pay, Alipay.\n\nNote: Some \"digital wallets\", including Google Pay and Apple Pay, facilitate\ncard payments. Those payments have the `CARD` type." }, { "name": "BUY_NOW_PAY_LATER", "description": "A Buy Now Pay Later payment." }, { "name": "SQUARE_ACCOUNT", "description": "A Square House Account payment." }, { "name": "OTHER", "description": "A form of tender that does not match any other value." } ], "description": "Indicates a tender's type.", "x-release-status": "PUBLIC" } } }