Pricing Templates
Log in Sign up
Integrations / Square Connect / ...

POST /v2/inventory/batch-change

Deprecated version of BatchChangeInventory after the endpoint URL is updated to conform to the standard convention.

Servers

Request headers

Name Type Required Description
Content-Type String Yes The media type of the request body.

Default value: "application/json"

Request body fields

Name Type Required Description
changes[] Array No

The set of physical counts and inventory adjustments to be made. Changes are applied based on the client-supplied timestamp and may be sent out of order.
changes[].measurement_unit Object No

Represents the unit used to measure a CatalogItemVariation and specifies the precision for decimal quantities.
changes[].measurement_unit.measurement_unit Object No

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.
changes[].measurement_unit.measurement_unit.length_unit String No

Represents a standard length unit.
changes[].measurement_unit.measurement_unit.volume_unit String No

Represents a standard volume unit.
changes[].measurement_unit.measurement_unit.time_unit String No

Represents a standard unit of time.
changes[].measurement_unit.measurement_unit.generic_unit String No

Reserved for API integrations that lack the ability to specify a real measurement unit
changes[].measurement_unit.measurement_unit.type String No

Represents the type of the measurement unit.
changes[].measurement_unit.measurement_unit.area_unit String No

Represents a standard area unit.
changes[].measurement_unit.measurement_unit.custom_unit Object No

The information needed to define a custom unit, provided by the seller.
changes[].measurement_unit.measurement_unit.custom_unit.abbreviation String Yes

The abbreviation of the custom unit, such as "bsh" (bushel). This appears in the cart for the Point of Sale app, and in reports.
changes[].measurement_unit.measurement_unit.custom_unit.name String Yes

The name of the custom unit, for example "bushel".
changes[].measurement_unit.measurement_unit.weight_unit String No

Represents a standard unit of weight or mass.
changes[].measurement_unit.precision Integer No

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
changes[].adjustment Object No

Represents a change in state or quantity of product inventory at a particular time and location.
changes[].adjustment.source Object No

Provides information about the application used to generate a change.
changes[].adjustment.source.name String No

Read-only display name assigned to the application (e.g. "Custom Application", "Square POS 4.74 for Android").
changes[].adjustment.source.application_id String No

Read-only Square ID assigned to the application. Only used for Product type EXTERNAL_API.
changes[].adjustment.source.product String No

Read-only Product type for the application.
changes[].adjustment.to_state String No

The inventory state of the related quantity of items after the adjustment.
changes[].adjustment.goods_receipt_id String No

The Square-generated ID of the goods receipt that caused the adjustment. Only relevant for state transitions from the Square for Retail app.
changes[].adjustment.quantity String No

The number of items affected by the adjustment as a decimal string. Can support up to 5 digits after the decimal point.
changes[].adjustment.total_price_money Object No

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 for more information.
changes[].adjustment.total_price_money.amount Integer No

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.
changes[].adjustment.total_price_money.currency String No

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.
changes[].adjustment.transaction_id String No

The Square-generated ID of the [Transaction][#type-transaction] that caused the adjustment. Only relevant for payment-related state transitions.
changes[].adjustment.catalog_object_type String No

The type of the CatalogObject being tracked. Tracking is only supported for the ITEM_VARIATION type.
changes[].adjustment.reference_id String No

An optional ID provided by the application to tie the InventoryAdjustment to an external system.
changes[].adjustment.id String No

A unique ID generated by Square for the InventoryAdjustment.
changes[].adjustment.location_id String No

The Square-generated ID of the Location where the related quantity of items is being tracked.
changes[].adjustment.purchase_order_id String No

The Square-generated ID of the purchase order that caused the adjustment. Only relevant for state transitions from the Square for Retail app.
changes[].adjustment.adjustment_group Object No
changes[].adjustment.adjustment_group.id String No

A unique ID generated by Square for the InventoryAdjustmentGroup.
changes[].adjustment.adjustment_group.to_state String No

Representative to_state for adjustments within group. For example, for a group adjustment from IN_STOCK to SOLD, the two component adjustments in the group can be from IN_STOCK to COMPOSED and from COMPOSED to SOLD. Here, the representative to_state of the InventoryAdjustmentGroup is SOLD.
changes[].adjustment.adjustment_group.root_adjustment_id String No

The inventory adjustment of the composed variation.
changes[].adjustment.adjustment_group.from_state String No

Representative from_state for adjustments within the group. For example, for a group adjustment from IN_STOCK to SOLD, there can be two component adjustments in the group: one from IN_STOCKto COMPOSED and the other one from COMPOSED to SOLD. Here, the representative from_state for the InventoryAdjustmentGroup is IN_STOCK.
changes[].adjustment.refund_id String No

The Square-generated ID of the [Refund][#type-refund] that caused the adjustment. Only relevant for refund-related state transitions.
changes[].adjustment.employee_id String No

The Square-generated ID of the Employee responsible for the inventory adjustment.
changes[].adjustment.created_at String No

An RFC 3339-formatted timestamp that indicates when the inventory adjustment is received.
changes[].adjustment.from_state String No

The inventory state of the related quantity of items before the adjustment.
changes[].adjustment.catalog_object_id String No

The Square-generated ID of the CatalogObject being tracked.
changes[].adjustment.occurred_at String No

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.
changes[].transfer Object No

Represents the transfer of a quantity of product inventory at a particular time from one location to another.
changes[].transfer.id String No

A unique ID generated by Square for the InventoryTransfer.
changes[].transfer.source Object No

Provides information about the application used to generate a change.
changes[].transfer.source.name String No

Read-only display name assigned to the application (e.g. "Custom Application", "Square POS 4.74 for Android").
changes[].transfer.source.application_id String No

Read-only Square ID assigned to the application. Only used for Product type EXTERNAL_API.
changes[].transfer.source.product String No

Read-only Product type for the application.
changes[].transfer.to_location_id String No

The Square-generated ID of the Location where the related quantity of items was tracked after the transfer.
changes[].transfer.from_location_id String No

The Square-generated ID of the Location where the related quantity of items was tracked before the transfer.
changes[].transfer.quantity String No

The number of items affected by the transfer as a decimal string. Can support up to 5 digits after the decimal point.
changes[].transfer.employee_id String No

The Square-generated ID of the Employee responsible for the inventory transfer.
changes[].transfer.created_at String No

An RFC 3339-formatted timestamp that indicates when Square received the transfer request.
changes[].transfer.state String No

The inventory state for the quantity of items being transferred.
changes[].transfer.catalog_object_id String No

The Square-generated ID of the CatalogObject being tracked.
changes[].transfer.catalog_object_type String No

The type of the CatalogObject being tracked.Tracking is only supported for the ITEM_VARIATION type.
changes[].transfer.occurred_at String No

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.
changes[].transfer.reference_id String No

An optional ID provided by the application to tie the InventoryTransfer to an external system.
changes[].type String No

Indicates how the inventory change is applied. See InventoryChangeType for all possible values.
changes[].measurement_unit_id String No

The ID of the CatalogMeasurementUnit object representing the catalog measurement unit associated with the inventory change.
changes[].physical_count Object No

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.
changes[].physical_count.id String No

A unique Square-generated ID for the InventoryPhysicalCount.
changes[].physical_count.source Object No

Provides information about the application used to generate a change.
changes[].physical_count.source.name String No

Read-only display name assigned to the application (e.g. "Custom Application", "Square POS 4.74 for Android").
changes[].physical_count.source.application_id String No

Read-only Square ID assigned to the application. Only used for Product type EXTERNAL_API.
changes[].physical_count.source.product String No

Read-only Product type for the application.
changes[].physical_count.location_id String No

The Square-generated ID of the Location where the related quantity of items is being tracked.
changes[].physical_count.quantity String No

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.
changes[].physical_count.employee_id String No

The Square-generated ID of the Employee responsible for the physical count.
changes[].physical_count.created_at String No

An RFC 3339-formatted timestamp that indicates when the physical count is received.
changes[].physical_count.state String No

The current inventory state for the related quantity of items.
changes[].physical_count.catalog_object_id String No

The Square-generated ID of the CatalogObject being tracked.
changes[].physical_count.catalog_object_type String No

The type of the CatalogObject being tracked. Tracking is only supported for the ITEM_VARIATION type.
changes[].physical_count.occurred_at String No

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.
changes[].physical_count.reference_id String No

An optional ID provided by the application to tie the InventoryPhysicalCount to an external system.
ignore_unchanged_counts Boolean No

Indicates whether the current physical count should be ignored if the quantity is unchanged since the last physical count. Default: true.
idempotency_key String Yes

A client-supplied, universally unique identifier (UUID) for the request.

See Idempotency in the API Development 101 section for more information.

How to start integrating

  1. Add HTTP Task to your workflow definition.
  2. Search for the API you want to integrate with and click on the name.
    • This loads the API reference documentation and prepares the Http request settings.
  3. Click Test request to test run your request to the API and see the API's response.
All third party trademarks (including logos and icons) are the property of their respective owners, which do not sponsor, authorize, or endorse this website.
Pricing Templates Integrations Blog Contact Us Help
© 2025 SimWorkflow
Terms of Service Privacy Policy