{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/square/main/json-schema/square-batch-change-inventory-request-schema.json", "title": "BatchChangeInventoryRequest", "x-generated": "2026-10-12", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/square-inventory-api-openapi.yml#/components/schemas/BatchChangeInventoryRequest", "type": "object", "x-release-status": "PUBLIC", "required": [ "idempotency_key" ], "properties": { "idempotency_key": { "type": "string", "description": "A client-supplied, universally unique identifier (UUID) for the\nrequest.\n\nSee [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) in the\n[API Development 101](https://developer.squareup.com/docs/buildbasics) section for more\ninformation.", "minLength": 1, "maxLength": 128 }, "changes": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/InventoryChange" }, "description": "The set of physical counts and inventory adjustments to be made.\nChanges are applied based on the client-supplied timestamp and may be sent\nout of order." }, "ignore_unchanged_counts": { "type": [ "boolean", "null" ], "description": "Indicates whether the current physical count should be ignored if\nthe quantity is unchanged since the last physical count. Default: `true`." } }, "x-sq-sdk-sample-code": { "csharp": "/sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.csharp", "java": "/sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.java", "javascript": "/sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.javascript", "php": "/sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.php", "python": "/sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.python", "ruby": "/sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.ruby" }, "$defs": { "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" } } }, "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" }, "InventoryAdjustment": { "type": "object", "description": "Represents a change in state or quantity of product inventory at a\nparticular time and location.", "x-release-status": "PUBLIC", "properties": { "id": { "type": "string", "description": "A unique ID generated by Square for the\n`InventoryAdjustment`.", "maxLength": 100 }, "reference_id": { "type": [ "string", "null" ], "description": "An optional ID provided by the application to tie the\n`InventoryAdjustment` to an external\nsystem.", "maxLength": 255 }, "from_state": { "$ref": "#/$defs/InventoryState", "description": "The [inventory state](entity:InventoryState) of the related quantity\nof items before the adjustment.\nSee [InventoryState](#type-inventorystate) for possible values" }, "to_state": { "$ref": "#/$defs/InventoryState", "description": "The [inventory state](entity:InventoryState) of the related quantity\nof items after the adjustment.\nSee [InventoryState](#type-inventorystate) for possible values" }, "location_id": { "type": [ "string", "null" ], "description": "The Square-generated ID of the [Location](entity:Location) where the related\nquantity of items is being tracked.", "maxLength": 100 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The Square-generated ID of the\n[CatalogObject](entity:CatalogObject) being tracked.", "maxLength": 100 }, "catalog_object_type": { "type": [ "string", "null" ], "description": "The [type](entity:CatalogObjectType) of the [CatalogObject](entity:CatalogObject) being tracked. \n\nThe Inventory API supports setting and reading the `\"catalog_object_type\": \"ITEM_VARIATION\"` field value. \nIn addition, it can also read the `\"catalog_object_type\": \"ITEM\"` field value that is set by the Square Restaurants app.", "maxLength": 14 }, "quantity": { "type": [ "string", "null" ], "description": "The number of items affected by the adjustment as a decimal string.\nCan support up to 5 digits after the decimal point.", "maxLength": 26 }, "total_price_money": { "$ref": "#/$defs/Money", "description": "The total price paid for goods associated with the\nadjustment. Present if and only if `to_state` is `SOLD`. Always\nnon-negative.", "readOnly": true }, "occurred_at": { "type": [ "string", "null" ], "description": "A client-generated RFC 3339-formatted timestamp that indicates when\nthe inventory adjustment took place. For inventory adjustment updates, the `occurred_at`\ntimestamp cannot be older than 24 hours or in the future relative to the\ntime of the request.", "maxLength": 34 }, "created_at": { "type": "string", "description": "An RFC 3339-formatted timestamp that indicates when the inventory adjustment is received.", "maxLength": 34, "readOnly": true }, "source": { "$ref": "#/$defs/SourceApplication", "description": "Information about the application that caused the\ninventory adjustment.", "readOnly": true }, "employee_id": { "type": [ "string", "null" ], "description": "The Square-generated ID of the [Employee](entity:Employee) responsible for the\ninventory adjustment.", "maxLength": 100 }, "team_member_id": { "type": [ "string", "null" ], "description": "The Square-generated ID of the [Team Member](entity:TeamMember) responsible for the\ninventory adjustment.", "maxLength": 100 }, "transaction_id": { "type": "string", "description": "The Square-generated ID of the [Transaction](entity:Transaction) that\ncaused the adjustment. Only relevant for payment-related state\ntransitions.", "maxLength": 255, "readOnly": true }, "refund_id": { "type": "string", "description": "The Square-generated ID of the [Refund](entity:Refund) that\ncaused the adjustment. Only relevant for refund-related state\ntransitions.", "maxLength": 255, "readOnly": true }, "purchase_order_id": { "type": "string", "description": "The Square-generated ID of the purchase order that caused the\nadjustment. Only relevant for state transitions from the Square for Retail\napp.", "maxLength": 100, "readOnly": true }, "goods_receipt_id": { "type": "string", "description": "The Square-generated ID of the goods receipt that caused the\nadjustment. Only relevant for state transitions from the Square for Retail\napp.", "maxLength": 100, "readOnly": true }, "adjustment_group": { "$ref": "#/$defs/InventoryAdjustmentGroup", "description": "An adjustment group bundling the related adjustments of item variations through stock conversions in a single inventory event.", "readOnly": true, "x-release-status": "BETA" } } }, "InventoryAdjustmentGroup": { "type": "object", "x-release-status": "BETA", "properties": { "id": { "type": "string", "description": "A unique ID generated by Square for the\n`InventoryAdjustmentGroup`.", "maxLength": 100, "readOnly": true }, "root_adjustment_id": { "type": "string", "description": "The inventory adjustment of the composed variation.", "maxLength": 100, "readOnly": true }, "from_state": { "$ref": "#/$defs/InventoryState", "description": "Representative `from_state` for adjustments within the group. For example, for a group adjustment from `IN_STOCK` to `SOLD`,\nthere can be two component adjustments in the group: one from `IN_STOCK`to `COMPOSED` and the other one from `COMPOSED` to `SOLD`.\nHere, the representative `from_state` for the `InventoryAdjustmentGroup` is `IN_STOCK`.\nSee [InventoryState](#type-inventorystate) for possible values", "readOnly": true }, "to_state": { "$ref": "#/$defs/InventoryState", "description": "Representative `to_state` for adjustments within group. For example, for a group adjustment from `IN_STOCK` to `SOLD`,\nthe two component adjustments in the group can be from `IN_STOCK` to `COMPOSED` and from `COMPOSED` to `SOLD`.\nHere, the representative `to_state` of the `InventoryAdjustmentGroup` is `SOLD`.\nSee [InventoryState](#type-inventorystate) for possible values", "readOnly": true } } }, "InventoryChange": { "type": "object", "description": "Represents a single physical count, inventory, adjustment, or transfer\nthat is part of the history of inventory changes for a particular\n[CatalogObject](entity:CatalogObject) instance.", "x-release-status": "PUBLIC", "properties": { "type": { "$ref": "#/$defs/InventoryChangeType", "description": "Indicates how the inventory change is applied. See\n[InventoryChangeType](entity:InventoryChangeType) for all possible values.\nSee [InventoryChangeType](#type-inventorychangetype) for possible values" }, "physical_count": { "$ref": "#/$defs/InventoryPhysicalCount", "description": "Contains details about the physical count when `type` is\n`PHYSICAL_COUNT`, and is unset for all other change types." }, "adjustment": { "$ref": "#/$defs/InventoryAdjustment", "description": "Contains details about the inventory adjustment when `type` is\n`ADJUSTMENT`, and is unset for all other change types." }, "transfer": { "$ref": "#/$defs/InventoryTransfer", "description": "Contains details about the inventory transfer when `type` is\n`TRANSFER`, and is unset for all other change types.\n\n_Note:_ An [InventoryTransfer](entity:InventoryTransfer) object can only be set in the input to the\n[BatchChangeInventory](api-endpoint:Inventory-BatchChangeInventory) endpoint when the seller has an active Retail Plus subscription." }, "measurement_unit": { "$ref": "#/$defs/CatalogMeasurementUnit", "description": "The [CatalogMeasurementUnit](entity:CatalogMeasurementUnit) object representing the catalog measurement unit associated with the inventory change.", "readOnly": true }, "measurement_unit_id": { "type": "string", "description": "The ID of the [CatalogMeasurementUnit](entity:CatalogMeasurementUnit) object representing the catalog measurement unit associated with the inventory change.", "readOnly": true } } }, "InventoryChangeType": { "type": "string", "enum": [ "PHYSICAL_COUNT", "ADJUSTMENT", "TRANSFER" ], "x-enum-elements": [ { "name": "PHYSICAL_COUNT", "description": "The change occurred as part of a physical count update." }, { "name": "ADJUSTMENT", "description": "The change occurred as part of the normal lifecycle of goods\n(e.g., as an inventory adjustment)." }, { "name": "TRANSFER", "description": "The change occurred as part of an inventory transfer." } ], "description": "Indicates how the inventory change was applied to a tracked product quantity.", "x-release-status": "PUBLIC" }, "InventoryPhysicalCount": { "type": "object", "description": "Represents the quantity of an item variation that is physically present\nat a specific location, verified by a seller or a seller's employee. For example,\na physical count might come from an employee counting the item variations on\nhand or from syncing with an external system.", "x-release-status": "PUBLIC", "properties": { "id": { "type": "string", "description": "A unique Square-generated ID for the\n[InventoryPhysicalCount](entity:InventoryPhysicalCount).", "maxLength": 100 }, "reference_id": { "type": [ "string", "null" ], "description": "An optional ID provided by the application to tie the\n[InventoryPhysicalCount](entity:InventoryPhysicalCount) to an external\nsystem.", "maxLength": 255 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The Square-generated ID of the\n[CatalogObject](entity:CatalogObject) being tracked.", "maxLength": 100 }, "catalog_object_type": { "type": [ "string", "null" ], "description": "The [type](entity:CatalogObjectType) of the [CatalogObject](entity:CatalogObject) being tracked. \n\nThe Inventory API supports setting and reading the `\"catalog_object_type\": \"ITEM_VARIATION\"` field value. \nIn addition, it can also read the `\"catalog_object_type\": \"ITEM\"` field value that is set by the Square Restaurants app.", "maxLength": 14 }, "state": { "$ref": "#/$defs/InventoryState", "description": "The current [inventory state](entity:InventoryState) for the related\nquantity of items.\nSee [InventoryState](#type-inventorystate) for possible values" }, "location_id": { "type": [ "string", "null" ], "description": "The Square-generated ID of the [Location](entity:Location) where the related\nquantity of items is being tracked.", "maxLength": 100 }, "quantity": { "type": [ "string", "null" ], "description": "The number of items affected by the physical count as a decimal string.\nThe number can support up to 5 digits after the decimal point.", "maxLength": 26 }, "source": { "$ref": "#/$defs/SourceApplication", "description": "Information about the application with which the\nphysical count is submitted.", "readOnly": true }, "employee_id": { "type": [ "string", "null" ], "description": "The Square-generated ID of the [Employee](entity:Employee) responsible for the\nphysical count.", "maxLength": 100 }, "team_member_id": { "type": [ "string", "null" ], "description": "The Square-generated ID of the [Team Member](entity:TeamMember) responsible for the\nphysical count.", "maxLength": 100 }, "occurred_at": { "type": [ "string", "null" ], "description": "A client-generated RFC 3339-formatted timestamp that indicates when\nthe physical count was examined. For physical count updates, the `occurred_at`\ntimestamp cannot be older than 24 hours or in the future relative to the\ntime of the request.", "maxLength": 34 }, "created_at": { "type": "string", "description": "An RFC 3339-formatted timestamp that indicates when the physical count is received.", "maxLength": 34, "readOnly": true } } }, "InventoryState": { "type": "string", "enum": [ "CUSTOM", "IN_STOCK", "SOLD", "RETURNED_BY_CUSTOMER", "RESERVED_FOR_SALE", "SOLD_ONLINE", "ORDERED_FROM_VENDOR", "RECEIVED_FROM_VENDOR", "IN_TRANSIT_TO", "NONE", "WASTE", "UNLINKED_RETURN", "COMPOSED", "DECOMPOSED", "SUPPORTED_BY_NEWER_VERSION", "IN_TRANSIT" ], "x-enum-elements": [ { "name": "CUSTOM", "description": "The related quantity of items are in a custom state. **READ-ONLY**:\nthe Inventory API cannot move quantities to or from this state." }, { "name": "IN_STOCK", "description": "The related quantity of items are on hand and available for sale." }, { "name": "SOLD", "description": "The related quantity of items were sold as part of an itemized\ntransaction. Quantities in the `SOLD` state are no longer tracked." }, { "name": "RETURNED_BY_CUSTOMER", "description": "The related quantity of items were returned through the Square Point\nof Sale application, but are not yet available for sale. **READ-ONLY**:\nthe Inventory API cannot move quantities to or from this state." }, { "name": "RESERVED_FOR_SALE", "description": "The related quantity of items are on hand, but not currently\navailable for sale. **READ-ONLY**: the Inventory API cannot move\nquantities to or from this state." }, { "name": "SOLD_ONLINE", "description": "The related quantity of items were sold online. **READ-ONLY**: the\nInventory API cannot move quantities to or from this state." }, { "name": "ORDERED_FROM_VENDOR", "description": "The related quantity of items were ordered from a vendor but not yet\nreceived. **READ-ONLY**: the Inventory API cannot move quantities to or\nfrom this state." }, { "name": "RECEIVED_FROM_VENDOR", "description": "The related quantity of items were received from a vendor but are\nnot yet available for sale. **READ-ONLY**: the Inventory API cannot move\nquantities to or from this state." }, { "name": "IN_TRANSIT_TO", "description": "Replaced by `IN_TRANSIT` to represent quantities\nof items that are in transit between locations." }, { "name": "NONE", "description": "A placeholder indicating that the related quantity of items are not\ncurrently tracked in Square. Transferring quantities from the `NONE` state\nto a tracked state (e.g., `IN_STOCK`) introduces stock into the system." }, { "name": "WASTE", "description": "The related quantity of items are lost or damaged and cannot be\nsold." }, { "name": "UNLINKED_RETURN", "description": "The related quantity of items were returned but not linked to a\nprevious transaction. Unlinked returns are not tracked in Square.\nTransferring a quantity from `UNLINKED_RETURN` to a tracked state (e.g.,\n`IN_STOCK`) introduces new stock into the system." }, { "name": "COMPOSED", "description": "The related quantity of items that are part of a composition consisting one or more components." }, { "name": "DECOMPOSED", "description": "The related quantity of items that are part of a component." }, { "name": "SUPPORTED_BY_NEWER_VERSION", "description": "This state is not supported by this version of the Square API. We recommend that you upgrade the client to use the appropriate version of the Square API supporting this state." }, { "name": "IN_TRANSIT", "description": "The related quantity of items are in transit between locations. **READ-ONLY:** the Inventory API cannot currently be used to move quantities to or from this inventory state." } ], "description": "Indicates the state of a tracked item quantity in the lifecycle of goods.", "x-release-status": "PUBLIC" }, "InventoryTransfer": { "type": "object", "description": "Represents the transfer of a quantity of product inventory at a\nparticular time from one location to another.", "x-release-status": "PUBLIC", "properties": { "id": { "type": "string", "description": "A unique ID generated by Square for the\n`InventoryTransfer`.", "maxLength": 100 }, "reference_id": { "type": [ "string", "null" ], "description": "An optional ID provided by the application to tie the\n`InventoryTransfer` to an external system.", "maxLength": 255 }, "state": { "$ref": "#/$defs/InventoryState", "description": "The [inventory state](entity:InventoryState) for the quantity of\nitems being transferred.\nSee [InventoryState](#type-inventorystate) for possible values" }, "from_location_id": { "type": [ "string", "null" ], "description": "The Square-generated ID of the [Location](entity:Location) where the related\nquantity of items was tracked before the transfer.", "maxLength": 100 }, "to_location_id": { "type": [ "string", "null" ], "description": "The Square-generated ID of the [Location](entity:Location) where the related\nquantity of items was tracked after the transfer.", "maxLength": 100 }, "catalog_object_id": { "type": [ "string", "null" ], "description": "The Square-generated ID of the\n[CatalogObject](entity:CatalogObject) being tracked.", "maxLength": 100 }, "catalog_object_type": { "type": [ "string", "null" ], "description": "The [type](entity:CatalogObjectType) of the [CatalogObject](entity:CatalogObject) being tracked. \n\nThe Inventory API supports setting and reading the `\"catalog_object_type\": \"ITEM_VARIATION\"` field value. \nIn addition, it can also read the `\"catalog_object_type\": \"ITEM\"` field value that is set by the Square Restaurants app.", "maxLength": 14 }, "quantity": { "type": [ "string", "null" ], "description": "The number of items affected by the transfer as a decimal string.\nCan support up to 5 digits after the decimal point.", "maxLength": 26 }, "occurred_at": { "type": [ "string", "null" ], "description": "A client-generated RFC 3339-formatted timestamp that indicates when\nthe transfer took place. For write actions, the `occurred_at` timestamp\ncannot be older than 24 hours or in the future relative to the time of the\nrequest.", "maxLength": 34 }, "created_at": { "type": "string", "description": "An RFC 3339-formatted timestamp that indicates when Square\nreceived the transfer request.", "maxLength": 34, "readOnly": true }, "source": { "$ref": "#/$defs/SourceApplication", "description": "Information about the application that initiated the\ninventory transfer.", "readOnly": true }, "employee_id": { "type": [ "string", "null" ], "description": "The Square-generated ID of the [Employee](entity:Employee) responsible for the\ninventory transfer.", "maxLength": 100 }, "team_member_id": { "type": [ "string", "null" ], "description": "The Square-generated ID of the [Team Member](entity:TeamMember) responsible for the\ninventory transfer.", "maxLength": 100 } } }, "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" }, "Money": { "type": "object", "description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.", "x-release-status": "PUBLIC", "properties": { "amount": { "type": [ "integer", "null" ], "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "format": "int64" }, "currency": { "$ref": "#/$defs/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](entity:Currency) for possible values.\nSee [Currency](#type-currency) for possible values" } } }, "Product": { "type": "string", "enum": [ "SQUARE_POS", "EXTERNAL_API", "BILLING", "APPOINTMENTS", "INVOICES", "ONLINE_STORE", "PAYROLL", "DASHBOARD", "ITEM_LIBRARY_IMPORT", "OTHER" ], "x-enum-elements": [ { "name": "SQUARE_POS", "description": "Square Point of Sale application." }, { "name": "EXTERNAL_API", "description": "Square Connect APIs (for example, Orders API or Checkout API)." }, { "name": "BILLING", "description": "A Square subscription (various products)." }, { "name": "APPOINTMENTS", "description": "Square Appointments." }, { "name": "INVOICES", "description": "Square Invoices." }, { "name": "ONLINE_STORE", "description": "Square Online Store." }, { "name": "PAYROLL", "description": "Square Payroll." }, { "name": "DASHBOARD", "description": "Square Dashboard." }, { "name": "ITEM_LIBRARY_IMPORT", "description": "Item Library Import." }, { "name": "OTHER", "description": "A Square product that does not match any other value." } ], "description": "Indicates the Square product used to generate a change.", "x-release-status": "PUBLIC" }, "SourceApplication": { "type": "object", "description": "Represents information about the application used to generate a change.", "x-release-status": "PUBLIC", "properties": { "product": { "$ref": "#/$defs/Product", "description": "__Read only__ The [product](entity:Product) type of the application.\nSee [Product](#type-product) for possible values" }, "application_id": { "type": [ "string", "null" ], "description": "__Read only__ The Square-assigned ID of the application. This field is used only if the\n[product](entity:Product) type is `EXTERNAL_API`." }, "name": { "type": [ "string", "null" ], "description": "__Read only__ The display name of the application\n(for example, `\"Custom Application\"` or `\"Square POS 4.74 for Android\"`)." } } } } }