RetrieveInventoryChanges

v1.0.0

Returns a set of physical counts and inventory adjustments for the provided at the requested s.

You can achieve the same result by calling and having the catalog_object_ids list contain a single element of the CatalogObject ID.

Results are paginated and sorted in descending order according to their occurred_at timestamp (newest first).

There are no limits on how far back the caller can page. This endpoint can be used to display recent changes for a specific item. For more sophisticated queries, use a batch endpoint.

Input

{
  "type": "object",
  "properties": {
    "catalog_object_id": {
      "type": "string"
    },
    "cursor": {
      "type": "string"
    },
    "location_ids": {
      "type": "string"
    }
  },
  "required": [
    "catalog_object_id"
  ],
  "additionalProperties": false
}

Output

{
  "type": "object",
  "properties": {
    "changes": {
      "type": "array",
      "description": "The set of inventory changes for the requested object and locations.",
      "items": {
        "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](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject) instance.",
        "properties": {
          "adjustment": {
            "type": "object",
            "description": "Represents a change in state or quantity of product inventory at a\nparticular time and location.",
            "properties": {
              "adjustment_group": {
                "type": "object",
                "properties": {
                  "from_state": {
                    "type": "string",
                    "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`."
                  },
                  "id": {
                    "type": "string",
                    "description": "A unique ID generated by Square for the\n`InventoryAdjustmentGroup`."
                  },
                  "root_adjustment_id": {
                    "type": "string",
                    "description": "The inventory adjustment of the composed variation."
                  },
                  "to_state": {
                    "type": "string",
                    "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`."
                  }
                }
              },
              "catalog_object_id": {
                "type": "string",
                "description": "The Square-generated ID of the\n[CatalogObject](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject) being tracked."
              },
              "catalog_object_type": {
                "type": "string",
                "description": "The [type](https://developer.squareup.com/reference/square_2021-08-18/enums/CatalogObjectType) of the\n[CatalogObject](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject) being tracked. Tracking is only\nsupported for the `ITEM_VARIATION` type."
              },
              "created_at": {
                "type": "string",
                "description": "An RFC 3339-formatted timestamp that indicates when the inventory adjustment is received."
              },
              "employee_id": {
                "type": "string",
                "description": "The Square-generated ID of the [Employee](https://developer.squareup.com/reference/square_2021-08-18/objects/Employee) responsible for the\ninventory adjustment."
              },
              "from_state": {
                "type": "string",
                "description": "The [inventory state](https://developer.squareup.com/reference/square_2021-08-18/enums/InventoryState) of the related quantity\nof items before the adjustment."
              },
              "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."
              },
              "id": {
                "type": "string",
                "description": "A unique ID generated by Square for the\n`InventoryAdjustment`."
              },
              "location_id": {
                "type": "string",
                "description": "The Square-generated ID of the [Location](https://developer.squareup.com/reference/square_2021-08-18/objects/Location) where the related\nquantity of items is being tracked."
              },
              "occurred_at": {
                "type": "string",
                "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."
              },
              "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."
              },
              "quantity": {
                "type": "string",
                "description": "The number of items affected by the adjustment as a decimal string.\nCan support up to 5 digits after the decimal point."
              },
              "reference_id": {
                "type": "string",
                "description": "An optional ID provided by the application to tie the\n`InventoryAdjustment` to an external\nsystem."
              },
              "refund_id": {
                "type": "string",
                "description": "The Square-generated ID of the [Refund][#type-refund] that\ncaused the adjustment. Only relevant for refund-related state\ntransitions."
              },
              "source": {
                "type": "object",
                "description": "Provides information about the application used to generate a change.",
                "properties": {
                  "application_id": {
                    "type": "string",
                    "description": "Read-only Square ID assigned to the application. Only used for\n[Product](https://developer.squareup.com/reference/square_2021-08-18/enums/Product) type `EXTERNAL_API`."
                  },
                  "name": {
                    "type": "string",
                    "description": "Read-only display name assigned to the application\n(e.g. `\"Custom Application\"`, `\"Square POS 4.74 for Android\"`)."
                  },
                  "product": {
                    "type": "string",
                    "description": "Read-only [Product](https://developer.squareup.com/reference/square_2021-08-18/enums/Product) type for the application."
                  }
                }
              },
              "to_state": {
                "type": "string",
                "description": "The [inventory state](https://developer.squareup.com/reference/square_2021-08-18/enums/InventoryState) of the related quantity\nof items after the adjustment."
              },
              "total_price_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.",
                "properties": {
                  "amount": {
                    "type": "integer",
                    "format": "int64",
                    "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."
                  },
                  "currency": {
                    "type": "string",
                    "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
                  }
                }
              },
              "transaction_id": {
                "type": "string",
                "description": "The Square-generated ID of the [Transaction][#type-transaction] that\ncaused the adjustment. Only relevant for payment-related state\ntransitions."
              }
            }
          },
          "measurement_unit": {
            "type": "object",
            "description": "Represents the unit used to measure a `CatalogItemVariation` and\nspecifies the precision for decimal quantities.",
            "properties": {
              "measurement_unit": {
                "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`.",
                "properties": {
                  "area_unit": {
                    "type": "string",
                    "description": "Represents a standard area unit."
                  },
                  "custom_unit": {
                    "type": "object",
                    "description": "The information needed to define a custom unit, provided by the seller.",
                    "required": [
                      "name",
                      "abbreviation"
                    ],
                    "properties": {
                      "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."
                      },
                      "name": {
                        "type": "string",
                        "description": "The name of the custom unit, for example \"bushel\"."
                      }
                    }
                  },
                  "generic_unit": {
                    "type": "string",
                    "description": "Reserved for API integrations that lack the ability to specify a real measurement unit"
                  },
                  "length_unit": {
                    "type": "string",
                    "description": "Represents a standard length unit."
                  },
                  "time_unit": {
                    "type": "string",
                    "description": "Represents a standard unit of time."
                  },
                  "type": {
                    "type": "string",
                    "description": "Represents the type of the measurement unit."
                  },
                  "volume_unit": {
                    "type": "string",
                    "description": "Represents a standard volume unit."
                  },
                  "weight_unit": {
                    "type": "string",
                    "description": "Represents a standard unit of weight or mass."
                  }
                }
              },
              "precision": {
                "type": "integer",
                "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"
              }
            }
          },
          "measurement_unit_id": {
            "type": "string",
            "description": "The ID of the [CatalogMeasurementUnit](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogMeasurementUnit) object representing the catalog measurement unit associated with the inventory change."
          },
          "physical_count": {
            "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.",
            "properties": {
              "catalog_object_id": {
                "type": "string",
                "description": "The Square-generated ID of the\n[CatalogObject](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject) being tracked."
              },
              "catalog_object_type": {
                "type": "string",
                "description": "The [type](https://developer.squareup.com/reference/square_2021-08-18/enums/CatalogObjectType) of the\n[CatalogObject](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject) being tracked. Tracking is only\nsupported for the `ITEM_VARIATION` type."
              },
              "created_at": {
                "type": "string",
                "description": "An RFC 3339-formatted timestamp that indicates when the physical count is received."
              },
              "employee_id": {
                "type": "string",
                "description": "The Square-generated ID of the [Employee](https://developer.squareup.com/reference/square_2021-08-18/objects/Employee) responsible for the\nphysical count."
              },
              "id": {
                "type": "string",
                "description": "A unique Square-generated ID for the\n[InventoryPhysicalCount](https://developer.squareup.com/reference/square_2021-08-18/objects/InventoryPhysicalCount)."
              },
              "location_id": {
                "type": "string",
                "description": "The Square-generated ID of the [Location](https://developer.squareup.com/reference/square_2021-08-18/objects/Location) where the related\nquantity of items is being tracked."
              },
              "occurred_at": {
                "type": "string",
                "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."
              },
              "quantity": {
                "type": "string",
                "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."
              },
              "reference_id": {
                "type": "string",
                "description": "An optional ID provided by the application to tie the\n[InventoryPhysicalCount](https://developer.squareup.com/reference/square_2021-08-18/objects/InventoryPhysicalCount) to an external\nsystem."
              },
              "source": {
                "type": "object",
                "description": "Provides information about the application used to generate a change.",
                "properties": {
                  "application_id": {
                    "type": "string",
                    "description": "Read-only Square ID assigned to the application. Only used for\n[Product](https://developer.squareup.com/reference/square_2021-08-18/enums/Product) type `EXTERNAL_API`."
                  },
                  "name": {
                    "type": "string",
                    "description": "Read-only display name assigned to the application\n(e.g. `\"Custom Application\"`, `\"Square POS 4.74 for Android\"`)."
                  },
                  "product": {
                    "type": "string",
                    "description": "Read-only [Product](https://developer.squareup.com/reference/square_2021-08-18/enums/Product) type for the application."
                  }
                }
              },
              "state": {
                "type": "string",
                "description": "The current [inventory state](https://developer.squareup.com/reference/square_2021-08-18/enums/InventoryState) for the related\nquantity of items."
              }
            }
          },
          "transfer": {
            "type": "object",
            "description": "Represents the transfer of a quantity of product inventory at a\nparticular time from one location to another.",
            "properties": {
              "catalog_object_id": {
                "type": "string",
                "description": "The Square-generated ID of the\n[CatalogObject](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject) being tracked."
              },
              "catalog_object_type": {
                "type": "string",
                "description": "The [type](https://developer.squareup.com/reference/square_2021-08-18/enums/CatalogObjectType) of the\n[CatalogObject](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject) being tracked.Tracking is only\nsupported for the `ITEM_VARIATION` type."
              },
              "created_at": {
                "type": "string",
                "description": "An RFC 3339-formatted timestamp that indicates when Square\nreceived the transfer request."
              },
              "employee_id": {
                "type": "string",
                "description": "The Square-generated ID of the [Employee](https://developer.squareup.com/reference/square_2021-08-18/objects/Employee) responsible for the\ninventory transfer."
              },
              "from_location_id": {
                "type": "string",
                "description": "The Square-generated ID of the [Location](https://developer.squareup.com/reference/square_2021-08-18/objects/Location) where the related\nquantity of items was tracked before the transfer."
              },
              "id": {
                "type": "string",
                "description": "A unique ID generated by Square for the\n`InventoryTransfer`."
              },
              "occurred_at": {
                "type": "string",
                "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."
              },
              "quantity": {
                "type": "string",
                "description": "The number of items affected by the transfer as a decimal string.\nCan support up to 5 digits after the decimal point."
              },
              "reference_id": {
                "type": "string",
                "description": "An optional ID provided by the application to tie the\n`InventoryTransfer` to an external system."
              },
              "source": {
                "type": "object",
                "description": "Provides information about the application used to generate a change.",
                "properties": {
                  "application_id": {
                    "type": "string",
                    "description": "Read-only Square ID assigned to the application. Only used for\n[Product](https://developer.squareup.com/reference/square_2021-08-18/enums/Product) type `EXTERNAL_API`."
                  },
                  "name": {
                    "type": "string",
                    "description": "Read-only display name assigned to the application\n(e.g. `\"Custom Application\"`, `\"Square POS 4.74 for Android\"`)."
                  },
                  "product": {
                    "type": "string",
                    "description": "Read-only [Product](https://developer.squareup.com/reference/square_2021-08-18/enums/Product) type for the application."
                  }
                }
              },
              "state": {
                "type": "string",
                "description": "The [inventory state](https://developer.squareup.com/reference/square_2021-08-18/enums/InventoryState) for the quantity of\nitems being transferred."
              },
              "to_location_id": {
                "type": "string",
                "description": "The Square-generated ID of the [Location](https://developer.squareup.com/reference/square_2021-08-18/objects/Location) where the related\nquantity of items was tracked after the transfer."
              }
            }
          },
          "type": {
            "type": "string",
            "description": "Indicates how the inventory change is applied. See\n[InventoryChangeType](https://developer.squareup.com/reference/square_2021-08-18/enums/InventoryChangeType) for all possible values."
          }
        }
      }
    },
    "cursor": {
      "type": "string",
      "description": "The pagination cursor to be used in a subsequent request. If unset,\nthis is the final response.\n\nSee the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information."
    },
    "errors": {
      "type": "array",
      "description": "Any errors that occurred during the request.",
      "items": {
        "type": "object",
        "description": "Represents an error encountered during a request to the Connect API.\n\nSee [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) for more information.",
        "required": [
          "category",
          "code"
        ],
        "properties": {
          "category": {
            "type": "string",
            "description": "The high-level category for the error."
          },
          "code": {
            "type": "string",
            "description": "The specific code of the error."
          },
          "detail": {
            "type": "string",
            "description": "A human-readable description of the error for debugging purposes."
          },
          "field": {
            "type": "string",
            "description": "The name of the field provided in the original request (if any) that\nthe error pertains to."
          }
        }
      }
    }
  }
}