--- title: "BatchChangeInventory" method: POST path: "/v2/inventory/changes/batch-create" tags: ["Inventory"] --- # BatchChangeInventory `POST /v2/inventory/changes/batch-create` Applies adjustments and counts to the provided item quantities. On success: returns the current calculated counts for all objects referenced in the request. On failure: returns a list of related errors. ## Request body - BatchChangeInventoryRequest - `idempotency_key` string, required — A client-supplied, universally unique identifier (UUID) for the request. See [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) in the [API Development 101](https://developer.squareup.com/docs/buildbasics) section for more information. - `changes` InventoryChange[], nullable — The set of physical counts and inventory adjustments to be made. Changes are applied based on the client-supplied timestamp and may be sent out of order. - `type` 'PHYSICAL_COUNT' | 'ADJUSTMENT' | 'TRANSFER' — Indicates how the inventory change was applied to a tracked product quantity. - `physical_count` InventoryPhysicalCount — Represents the quantity of an item variation that is physically present at a specific location, verified by a seller or a seller's employee. For example, a physical count might come from an employee counting the item variations on hand or from syncing with an external system. - `id` string — A unique Square-generated ID for the [InventoryPhysicalCount](entity:InventoryPhysicalCount). - `reference_id` string, nullable — An optional ID provided by the application to tie the [InventoryPhysicalCount](entity:InventoryPhysicalCount) to an external system. - `catalog_object_id` string, nullable — The Square-generated ID of the [CatalogObject](entity:CatalogObject) being tracked. - `catalog_object_type` string, nullable — The [type](entity:CatalogObjectType) of the [CatalogObject](entity:CatalogObject) being tracked. The Inventory API supports setting and reading the `"catalog_object_type": "ITEM_VARIATION"` field value. In addition, it can also read the `"catalog_object_type": "ITEM"` field value that is set by the Square Restaurants app. - `state` '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' — Indicates the state of a tracked item quantity in the lifecycle of goods. - `location_id` string, nullable — The Square-generated ID of the [Location](entity:Location) where the related quantity of items is being tracked. - `quantity` string, nullable — The number of items affected by the physical count as a decimal string. The number can support up to 5 digits after the decimal point. - `source` SourceApplication — Represents information about the application used to generate a change. - `product` 'SQUARE_POS' | 'EXTERNAL_API' | 'BILLING' | 'APPOINTMENTS' | 'INVOICES' | 'ONLINE_STORE' | 'PAYROLL' | 'DASHBOARD' | 'ITEM_LIBRARY_IMPORT' | 'OTHER' — Indicates the Square product used to generate a change. - `application_id` string, nullable — __Read only__ The Square-assigned ID of the application. This field is used only if the [product](entity:Product) type is `EXTERNAL_API`. - `name` string, nullable — __Read only__ The display name of the application (for example, `"Custom Application"` or `"Square POS 4.74 for Android"`). - `employee_id` string, nullable — The Square-generated ID of the [Employee](entity:Employee) responsible for the physical count. - `team_member_id` string, nullable — The Square-generated ID of the [Team Member](entity:TeamMember) responsible for the physical count. - `occurred_at` string, nullable — A client-generated RFC 3339-formatted timestamp that indicates when the physical count was examined. For physical count updates, the `occurred_at` timestamp cannot be older than 24 hours or in the future relative to the time of the request. - `created_at` string — An RFC 3339-formatted timestamp that indicates when the physical count is received. - `adjustment` InventoryAdjustment — Represents a change in state or quantity of product inventory at a particular time and location. - `id` string — A unique ID generated by Square for the `InventoryAdjustment`. - `reference_id` string, nullable — An optional ID provided by the application to tie the `InventoryAdjustment` to an external system. - `from_state` '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' — Indicates the state of a tracked item quantity in the lifecycle of goods. - `to_state` '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' — Indicates the state of a tracked item quantity in the lifecycle of goods. - `location_id` string, nullable — The Square-generated ID of the [Location](entity:Location) where the related quantity of items is being tracked. - `catalog_object_id` string, nullable — The Square-generated ID of the [CatalogObject](entity:CatalogObject) being tracked. - `catalog_object_type` string, nullable — The [type](entity:CatalogObjectType) of the [CatalogObject](entity:CatalogObject) being tracked. The Inventory API supports setting and reading the `"catalog_object_type": "ITEM_VARIATION"` field value. In addition, it can also read the `"catalog_object_type": "ITEM"` field value that is set by the Square Restaurants app. - `quantity` string, nullable — The number of items affected by the adjustment as a decimal string. Can support up to 5 digits after the decimal point. - `total_price_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer, nullable — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` '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' — Indicates the associated currency for an amount of money. Values correspond to [ISO 4217](https://wikipedia.org/wiki/ISO_4217). - `occurred_at` string, nullable — A client-generated RFC 3339-formatted timestamp that indicates when the inventory adjustment took place. For inventory adjustment updates, the `occurred_at` timestamp cannot be older than 24 hours or in the future relative to the time of the request. - `created_at` string — An RFC 3339-formatted timestamp that indicates when the inventory adjustment is received. - `source` SourceApplication — Represents information about the application used to generate a change. - `product` 'SQUARE_POS' | 'EXTERNAL_API' | 'BILLING' | 'APPOINTMENTS' | 'INVOICES' | 'ONLINE_STORE' | 'PAYROLL' | 'DASHBOARD' | 'ITEM_LIBRARY_IMPORT' | 'OTHER' — Indicates the Square product used to generate a change. - `application_id` string, nullable — __Read only__ The Square-assigned ID of the application. This field is used only if the [product](entity:Product) type is `EXTERNAL_API`. - `name` string, nullable — __Read only__ The display name of the application (for example, `"Custom Application"` or `"Square POS 4.74 for Android"`). - `employee_id` string, nullable — The Square-generated ID of the [Employee](entity:Employee) responsible for the inventory adjustment. - `team_member_id` string, nullable — The Square-generated ID of the [Team Member](entity:TeamMember) responsible for the inventory adjustment. - `transaction_id` string — The Square-generated ID of the [Transaction](entity:Transaction) that caused the adjustment. Only relevant for payment-related state transitions. - `refund_id` string — The Square-generated ID of the [Refund](entity:Refund) that caused the adjustment. Only relevant for refund-related state transitions. - `purchase_order_id` string — The Square-generated ID of the purchase order that caused the adjustment. Only relevant for state transitions from the Square for Retail app. - `goods_receipt_id` string — The Square-generated ID of the goods receipt that caused the adjustment. Only relevant for state transitions from the Square for Retail app. - `adjustment_group` InventoryAdjustmentGroup - `id` string — A unique ID generated by Square for the `InventoryAdjustmentGroup`. - `root_adjustment_id` string — The inventory adjustment of the composed variation. - `from_state` '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' — Indicates the state of a tracked item quantity in the lifecycle of goods. - `to_state` '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' — Indicates the state of a tracked item quantity in the lifecycle of goods. - `transfer` InventoryTransfer — Represents the transfer of a quantity of product inventory at a particular time from one location to another. - `id` string — A unique ID generated by Square for the `InventoryTransfer`. - `reference_id` string, nullable — An optional ID provided by the application to tie the `InventoryTransfer` to an external system. - `state` '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' — Indicates the state of a tracked item quantity in the lifecycle of goods. - `from_location_id` string, nullable — The Square-generated ID of the [Location](entity:Location) where the related quantity of items was tracked before the transfer. - `to_location_id` string, nullable — The Square-generated ID of the [Location](entity:Location) where the related quantity of items was tracked after the transfer. - `catalog_object_id` string, nullable — The Square-generated ID of the [CatalogObject](entity:CatalogObject) being tracked. - `catalog_object_type` string, nullable — The [type](entity:CatalogObjectType) of the [CatalogObject](entity:CatalogObject) being tracked. The Inventory API supports setting and reading the `"catalog_object_type": "ITEM_VARIATION"` field value. In addition, it can also read the `"catalog_object_type": "ITEM"` field value that is set by the Square Restaurants app. - `quantity` string, nullable — The number of items affected by the transfer as a decimal string. Can support up to 5 digits after the decimal point. - `occurred_at` string, nullable — A client-generated RFC 3339-formatted timestamp that indicates when the transfer took place. For write actions, the `occurred_at` timestamp cannot be older than 24 hours or in the future relative to the time of the request. - `created_at` string — An RFC 3339-formatted timestamp that indicates when Square received the transfer request. - `source` SourceApplication — Represents information about the application used to generate a change. - `product` 'SQUARE_POS' | 'EXTERNAL_API' | 'BILLING' | 'APPOINTMENTS' | 'INVOICES' | 'ONLINE_STORE' | 'PAYROLL' | 'DASHBOARD' | 'ITEM_LIBRARY_IMPORT' | 'OTHER' — Indicates the Square product used to generate a change. - `application_id` string, nullable — __Read only__ The Square-assigned ID of the application. This field is used only if the [product](entity:Product) type is `EXTERNAL_API`. - `name` string, nullable — __Read only__ The display name of the application (for example, `"Custom Application"` or `"Square POS 4.74 for Android"`). - `employee_id` string, nullable — The Square-generated ID of the [Employee](entity:Employee) responsible for the inventory transfer. - `team_member_id` string, nullable — The Square-generated ID of the [Team Member](entity:TeamMember) responsible for the inventory transfer. - `measurement_unit` CatalogMeasurementUnit — Represents the unit used to measure a `CatalogItemVariation` and specifies the precision for decimal quantities. - `measurement_unit` MeasurementUnit — Represents a unit of measurement to use with a quantity, such as ounces or inches. Exactly one of the following fields are required: `custom_unit`, `area_unit`, `length_unit`, `volume_unit`, and `weight_unit`. - `custom_unit` MeasurementUnitCustom — The information needed to define a custom unit, provided by the seller. - `name` string, required — The name of the custom unit, for example "bushel". - `abbreviation` string, required — The abbreviation of the custom unit, such as "bsh" (bushel). This appears in the cart for the Point of Sale app, and in reports. - `area_unit` 'IMPERIAL_ACRE' | 'IMPERIAL_SQUARE_INCH' | 'IMPERIAL_SQUARE_FOOT' | 'IMPERIAL_SQUARE_YARD' | 'IMPERIAL_SQUARE_MILE' | 'METRIC_SQUARE_CENTIMETER' | 'METRIC_SQUARE_METER' | 'METRIC_SQUARE_KILOMETER' — Unit of area used to measure a quantity. - `length_unit` 'IMPERIAL_INCH' | 'IMPERIAL_FOOT' | 'IMPERIAL_YARD' | 'IMPERIAL_MILE' | 'METRIC_MILLIMETER' | 'METRIC_CENTIMETER' | 'METRIC_METER' | 'METRIC_KILOMETER' — The unit of length used to measure a quantity. - `volume_unit` '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' — The unit of volume used to measure a quantity. - `weight_unit` 'IMPERIAL_WEIGHT_OUNCE' | 'IMPERIAL_POUND' | 'IMPERIAL_STONE' | 'METRIC_MILLIGRAM' | 'METRIC_GRAM' | 'METRIC_KILOGRAM' — Unit of weight used to measure a quantity. - `generic_unit` 'UNIT' - `time_unit` 'GENERIC_MILLISECOND' | 'GENERIC_SECOND' | 'GENERIC_MINUTE' | 'GENERIC_HOUR' | 'GENERIC_DAY' — Unit of time used to measure a quantity (a duration). - `type` 'TYPE_CUSTOM' | 'TYPE_AREA' | 'TYPE_LENGTH' | 'TYPE_VOLUME' | 'TYPE_WEIGHT' | 'TYPE_GENERIC' — Describes the type of this unit and indicates which field contains the unit information. This is an ‘open’ enum. - `precision` integer, nullable — An integer between 0 and 5 that represents the maximum number of positions allowed after the decimal in quantities measured with this unit. For example: - if the precision is 0, the quantity can be 1, 2, 3, etc. - if the precision is 1, the quantity can be 0.1, 0.2, etc. - if the precision is 2, the quantity can be 0.01, 0.12, etc. Default: 3 - `measurement_unit_id` string — The ID of the [CatalogMeasurementUnit](entity:CatalogMeasurementUnit) object representing the catalog measurement unit associated with the inventory change. - `ignore_unchanged_counts` boolean, nullable — Indicates whether the current physical count should be ignored if the quantity is unchanged since the last physical count. Default: `true`. ## Response `200` Success - BatchChangeInventoryResponse - `errors` Error[] — Any errors that occurred during the request. - `category` 'API_ERROR' | 'AUTHENTICATION_ERROR' | 'INVALID_REQUEST_ERROR' | 'RATE_LIMIT_ERROR' | 'PAYMENT_METHOD_ERROR' | 'REFUND_ERROR' | 'MERCHANT_SUBSCRIPTION_ERROR' | 'EXTERNAL_VENDOR_ERROR', required — Indicates which high-level category of error has occurred during a request to the Connect API. - `code` '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' | 'READER_DECLINED' | '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_ERROR_PAYMENT_NEEDS_COMPLETION' | 'REFUND_DECLINED' | 'INSUFFICIENT_PERMISSIONS_FOR_REFUND' | 'INVALID_CARD_DATA' | 'SOURCE_USED' | 'SOURCE_EXPIRED' | 'UNSUPPORTED_LOYALTY_REWARD_TIER' | 'LOCATION_MISMATCH' | 'ORDER_UNPAID_NOT_RETURNABLE' | 'PARTIAL_PAYMENT_DELAY_CAPTURE_NOT_SUPPORTED' | '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' | 'PAYMENT_SOURCE_NOT_ENABLED_FOR_TARGET' | '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', required — Indicates the specific error that occurred during a request to a Square API. - `detail` string — A human-readable description of the error for debugging purposes. - `field` string — The name of the field provided in the original request (if any) that the error pertains to. - `counts` InventoryCount[] — The current counts for all objects referenced in the request. - `catalog_object_id` string, nullable — The Square-generated ID of the [CatalogObject](entity:CatalogObject) being tracked. - `catalog_object_type` string, nullable — The [type](entity:CatalogObjectType) of the [CatalogObject](entity:CatalogObject) being tracked. The Inventory API supports setting and reading the `"catalog_object_type": "ITEM_VARIATION"` field value. In addition, it can also read the `"catalog_object_type": "ITEM"` field value that is set by the Square Restaurants app. - `state` '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' — Indicates the state of a tracked item quantity in the lifecycle of goods. - `location_id` string, nullable — The Square-generated ID of the [Location](entity:Location) where the related quantity of items is being tracked. - `quantity` string, nullable — The number of items affected by the estimated count as a decimal string. Can support up to 5 digits after the decimal point. - `calculated_at` string — An RFC 3339-formatted timestamp that indicates when the most recent physical count or adjustment affecting the estimated count is received. - `is_estimated` boolean — Whether the inventory count is for composed variation (TRUE) or not (FALSE). If true, the inventory count will not be present in the response of any of these endpoints: [BatchChangeInventory](api-endpoint:Inventory-BatchChangeInventory), [BatchRetrieveInventoryChanges](api-endpoint:Inventory-BatchRetrieveInventoryChanges), [BatchRetrieveInventoryCounts](api-endpoint:Inventory-BatchRetrieveInventoryCounts), and [RetrieveInventoryChanges](api-endpoint:Inventory-RetrieveInventoryChanges). - `changes` InventoryChange[] — Changes created for the request. - `type` 'PHYSICAL_COUNT' | 'ADJUSTMENT' | 'TRANSFER' — Indicates how the inventory change was applied to a tracked product quantity. - `physical_count` InventoryPhysicalCount — Represents the quantity of an item variation that is physically present at a specific location, verified by a seller or a seller's employee. For example, a physical count might come from an employee counting the item variations on hand or from syncing with an external system. - `id` string — A unique Square-generated ID for the [InventoryPhysicalCount](entity:InventoryPhysicalCount). - `reference_id` string, nullable — An optional ID provided by the application to tie the [InventoryPhysicalCount](entity:InventoryPhysicalCount) to an external system. - `catalog_object_id` string, nullable — The Square-generated ID of the [CatalogObject](entity:CatalogObject) being tracked. - `catalog_object_type` string, nullable — The [type](entity:CatalogObjectType) of the [CatalogObject](entity:CatalogObject) being tracked. The Inventory API supports setting and reading the `"catalog_object_type": "ITEM_VARIATION"` field value. In addition, it can also read the `"catalog_object_type": "ITEM"` field value that is set by the Square Restaurants app. - `state` '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' — Indicates the state of a tracked item quantity in the lifecycle of goods. - `location_id` string, nullable — The Square-generated ID of the [Location](entity:Location) where the related quantity of items is being tracked. - `quantity` string, nullable — The number of items affected by the physical count as a decimal string. The number can support up to 5 digits after the decimal point. - `source` SourceApplication — Represents information about the application used to generate a change. - `product` 'SQUARE_POS' | 'EXTERNAL_API' | 'BILLING' | 'APPOINTMENTS' | 'INVOICES' | 'ONLINE_STORE' | 'PAYROLL' | 'DASHBOARD' | 'ITEM_LIBRARY_IMPORT' | 'OTHER' — Indicates the Square product used to generate a change. - `application_id` string, nullable — __Read only__ The Square-assigned ID of the application. This field is used only if the [product](entity:Product) type is `EXTERNAL_API`. - `name` string, nullable — __Read only__ The display name of the application (for example, `"Custom Application"` or `"Square POS 4.74 for Android"`). - `employee_id` string, nullable — The Square-generated ID of the [Employee](entity:Employee) responsible for the physical count. - `team_member_id` string, nullable — The Square-generated ID of the [Team Member](entity:TeamMember) responsible for the physical count. - `occurred_at` string, nullable — A client-generated RFC 3339-formatted timestamp that indicates when the physical count was examined. For physical count updates, the `occurred_at` timestamp cannot be older than 24 hours or in the future relative to the time of the request. - `created_at` string — An RFC 3339-formatted timestamp that indicates when the physical count is received. - `adjustment` InventoryAdjustment — Represents a change in state or quantity of product inventory at a particular time and location. - `id` string — A unique ID generated by Square for the `InventoryAdjustment`. - `reference_id` string, nullable — An optional ID provided by the application to tie the `InventoryAdjustment` to an external system. - `from_state` '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' — Indicates the state of a tracked item quantity in the lifecycle of goods. - `to_state` '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' — Indicates the state of a tracked item quantity in the lifecycle of goods. - `location_id` string, nullable — The Square-generated ID of the [Location](entity:Location) where the related quantity of items is being tracked. - `catalog_object_id` string, nullable — The Square-generated ID of the [CatalogObject](entity:CatalogObject) being tracked. - `catalog_object_type` string, nullable — The [type](entity:CatalogObjectType) of the [CatalogObject](entity:CatalogObject) being tracked. The Inventory API supports setting and reading the `"catalog_object_type": "ITEM_VARIATION"` field value. In addition, it can also read the `"catalog_object_type": "ITEM"` field value that is set by the Square Restaurants app. - `quantity` string, nullable — The number of items affected by the adjustment as a decimal string. Can support up to 5 digits after the decimal point. - `total_price_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer, nullable — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` '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' — Indicates the associated currency for an amount of money. Values correspond to [ISO 4217](https://wikipedia.org/wiki/ISO_4217). - `occurred_at` string, nullable — A client-generated RFC 3339-formatted timestamp that indicates when the inventory adjustment took place. For inventory adjustment updates, the `occurred_at` timestamp cannot be older than 24 hours or in the future relative to the time of the request. - `created_at` string — An RFC 3339-formatted timestamp that indicates when the inventory adjustment is received. - `source` SourceApplication — Represents information about the application used to generate a change. - `product` 'SQUARE_POS' | 'EXTERNAL_API' | 'BILLING' | 'APPOINTMENTS' | 'INVOICES' | 'ONLINE_STORE' | 'PAYROLL' | 'DASHBOARD' | 'ITEM_LIBRARY_IMPORT' | 'OTHER' — Indicates the Square product used to generate a change. - `application_id` string, nullable — __Read only__ The Square-assigned ID of the application. This field is used only if the [product](entity:Product) type is `EXTERNAL_API`. - `name` string, nullable — __Read only__ The display name of the application (for example, `"Custom Application"` or `"Square POS 4.74 for Android"`). - `employee_id` string, nullable — The Square-generated ID of the [Employee](entity:Employee) responsible for the inventory adjustment. - `team_member_id` string, nullable — The Square-generated ID of the [Team Member](entity:TeamMember) responsible for the inventory adjustment. - `transaction_id` string — The Square-generated ID of the [Transaction](entity:Transaction) that caused the adjustment. Only relevant for payment-related state transitions. - `refund_id` string — The Square-generated ID of the [Refund](entity:Refund) that caused the adjustment. Only relevant for refund-related state transitions. - `purchase_order_id` string — The Square-generated ID of the purchase order that caused the adjustment. Only relevant for state transitions from the Square for Retail app. - `goods_receipt_id` string — The Square-generated ID of the goods receipt that caused the adjustment. Only relevant for state transitions from the Square for Retail app. - `adjustment_group` InventoryAdjustmentGroup - `id` string — A unique ID generated by Square for the `InventoryAdjustmentGroup`. - `root_adjustment_id` string — The inventory adjustment of the composed variation. - `from_state` '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' — Indicates the state of a tracked item quantity in the lifecycle of goods. - `to_state` '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' — Indicates the state of a tracked item quantity in the lifecycle of goods. - `transfer` InventoryTransfer — Represents the transfer of a quantity of product inventory at a particular time from one location to another. - `id` string — A unique ID generated by Square for the `InventoryTransfer`. - `reference_id` string, nullable — An optional ID provided by the application to tie the `InventoryTransfer` to an external system. - `state` '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' — Indicates the state of a tracked item quantity in the lifecycle of goods. - `from_location_id` string, nullable — The Square-generated ID of the [Location](entity:Location) where the related quantity of items was tracked before the transfer. - `to_location_id` string, nullable — The Square-generated ID of the [Location](entity:Location) where the related quantity of items was tracked after the transfer. - `catalog_object_id` string, nullable — The Square-generated ID of the [CatalogObject](entity:CatalogObject) being tracked. - `catalog_object_type` string, nullable — The [type](entity:CatalogObjectType) of the [CatalogObject](entity:CatalogObject) being tracked. The Inventory API supports setting and reading the `"catalog_object_type": "ITEM_VARIATION"` field value. In addition, it can also read the `"catalog_object_type": "ITEM"` field value that is set by the Square Restaurants app. - `quantity` string, nullable — The number of items affected by the transfer as a decimal string. Can support up to 5 digits after the decimal point. - `occurred_at` string, nullable — A client-generated RFC 3339-formatted timestamp that indicates when the transfer took place. For write actions, the `occurred_at` timestamp cannot be older than 24 hours or in the future relative to the time of the request. - `created_at` string — An RFC 3339-formatted timestamp that indicates when Square received the transfer request. - `source` SourceApplication — Represents information about the application used to generate a change. - `product` 'SQUARE_POS' | 'EXTERNAL_API' | 'BILLING' | 'APPOINTMENTS' | 'INVOICES' | 'ONLINE_STORE' | 'PAYROLL' | 'DASHBOARD' | 'ITEM_LIBRARY_IMPORT' | 'OTHER' — Indicates the Square product used to generate a change. - `application_id` string, nullable — __Read only__ The Square-assigned ID of the application. This field is used only if the [product](entity:Product) type is `EXTERNAL_API`. - `name` string, nullable — __Read only__ The display name of the application (for example, `"Custom Application"` or `"Square POS 4.74 for Android"`). - `employee_id` string, nullable — The Square-generated ID of the [Employee](entity:Employee) responsible for the inventory transfer. - `team_member_id` string, nullable — The Square-generated ID of the [Team Member](entity:TeamMember) responsible for the inventory transfer. - `measurement_unit` CatalogMeasurementUnit — Represents the unit used to measure a `CatalogItemVariation` and specifies the precision for decimal quantities. - `measurement_unit` MeasurementUnit — Represents a unit of measurement to use with a quantity, such as ounces or inches. Exactly one of the following fields are required: `custom_unit`, `area_unit`, `length_unit`, `volume_unit`, and `weight_unit`. - `custom_unit` MeasurementUnitCustom — The information needed to define a custom unit, provided by the seller. - `name` string, required — The name of the custom unit, for example "bushel". - `abbreviation` string, required — The abbreviation of the custom unit, such as "bsh" (bushel). This appears in the cart for the Point of Sale app, and in reports. - `area_unit` 'IMPERIAL_ACRE' | 'IMPERIAL_SQUARE_INCH' | 'IMPERIAL_SQUARE_FOOT' | 'IMPERIAL_SQUARE_YARD' | 'IMPERIAL_SQUARE_MILE' | 'METRIC_SQUARE_CENTIMETER' | 'METRIC_SQUARE_METER' | 'METRIC_SQUARE_KILOMETER' — Unit of area used to measure a quantity. - `length_unit` 'IMPERIAL_INCH' | 'IMPERIAL_FOOT' | 'IMPERIAL_YARD' | 'IMPERIAL_MILE' | 'METRIC_MILLIMETER' | 'METRIC_CENTIMETER' | 'METRIC_METER' | 'METRIC_KILOMETER' — The unit of length used to measure a quantity. - `volume_unit` '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' — The unit of volume used to measure a quantity. - `weight_unit` 'IMPERIAL_WEIGHT_OUNCE' | 'IMPERIAL_POUND' | 'IMPERIAL_STONE' | 'METRIC_MILLIGRAM' | 'METRIC_GRAM' | 'METRIC_KILOGRAM' — Unit of weight used to measure a quantity. - `generic_unit` 'UNIT' - `time_unit` 'GENERIC_MILLISECOND' | 'GENERIC_SECOND' | 'GENERIC_MINUTE' | 'GENERIC_HOUR' | 'GENERIC_DAY' — Unit of time used to measure a quantity (a duration). - `type` 'TYPE_CUSTOM' | 'TYPE_AREA' | 'TYPE_LENGTH' | 'TYPE_VOLUME' | 'TYPE_WEIGHT' | 'TYPE_GENERIC' — Describes the type of this unit and indicates which field contains the unit information. This is an ‘open’ enum. - `precision` integer, nullable — An integer between 0 and 5 that represents the maximum number of positions allowed after the decimal in quantities measured with this unit. For example: - if the precision is 0, the quantity can be 1, 2, 3, etc. - if the precision is 1, the quantity can be 0.1, 0.2, etc. - if the precision is 2, the quantity can be 0.01, 0.12, etc. Default: 3 - `measurement_unit_id` string — The ID of the [CatalogMeasurementUnit](entity:CatalogMeasurementUnit) object representing the catalog measurement unit associated with the inventory change. --- [API](https://skmtc.net/square/apis/connect-api.md) · [All operations](https://skmtc.net/square/apis/connect-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/connect-api/versions/6a5164284e41/schema)