Inventory API

Handle Inventory Event Notifications

The Inventory API exposes a webhook to dispatch inventory.count.updated events every time an inventory quantity is updated for a catalog item variation.

Your application can subscribe to the webhook to receive inventory.count.updated event notifications to track inventory for item variations and changes in near real time reliably and accurately.

How inventory event notifications work Permalink Get a link to this section

Each inventory event notification includes basic information, such as the event type and event ID. The data field of each webhook notification contains detailed information about the specific event.

Inventory.count.updated event Permalink Get a link to this section

An inventory.updated event is invoked when an inventory count is updated. An inventory count can be updated explicitly in the Square Seller Dashboard or using the Square Inventory API BatchChangeInventory endpoint. It can also be updated automatically when an order is placed and paid for.

The following shows an example of the inventory.count.updated event:

{
  "merchant_id": "6SSW7HV8K2ST5",
  "type": "inventory.count.updated",
  "event_id": "df5f3813-a913-45a1-94e9-fdc3f7d5e3b6",
  "created_at": "2020-12-29T18:38:45.455006797Z",
  "data": {
    "type": "inventory",
    "id": "84e4ac73-d605-4dbd-a9e5-ffff794ddb9d",
    "object": {
      "inventory_counts": [
        {
          "calculated_at": "2020-12-29T18:38:45.10296Z",
          "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
          "catalog_object_type": "ITEM_VARIATION",
          "location_id": "EF6D9SACKWBKZ",
          "quantity": "90",
          "state": "IN_STOCK"
        }
      ]
    }
  }
}

State adjustments Permalink Get a link to this section

The inventory.count.updated webhook event also sends notifications when an item variation stock changes state. For state adjustments, inventory.count.updated sends a single notification containing two inventory counts: one count that describes the quantity and state before the state change and one that describes the quantity and state after the state change.

Bulk updates Permalink Get a link to this section

A single webhook notification can contain up to 100 inventory counts. If a bulk update includes more than 100 updates, the event data spans multiple webhook notifications.

Process inventory event notifications Permalink Get a link to this section

To process inventory event notifications, you need to perform the following tasks:

  • Meet requirements and understand limitations.

  • Subscribe to inventory event notifications.

  • Handle received event notifications.

  • Test and deploy your application.

The following sections describe each of these tasks. For information about general webhooks requirements, components, and processes, see Features of Square Webhooks.

Requirements and limitations Permalink Get a link to this section

The following requirements and limitations apply to webhooks for inventory events:

  • Your notification URL must be a publicly available HTTPS URL. It must also return an HTTP 2xx response code within 10 seconds of receiving a notification.

  • Applications that use OAuth must have INVENTORY_READ permission to subscribe to an inventory event and receive notifications.

Subscribe to inventory event notifications Permalink Get a link to this section

To subscribe to inventory event notifications, you can configure webhooks for your Square inventory application. A webhook registers the URL that Square should send notifications to, the events you want to be notified about, and the Square API version.

To configure a webhook

  1. In the Developer Dashboard, open the application to which you want to subscribe.

  2. In the navigation pane, choose Webhooks.

  3. At the top of the page, choose Sandbox or Production. Use the Sandbox environment for testing.

  4. Choose Add Endpoint, and then configure the endpoint:

    1. For Webhook Name, enter a name such as Inventory Webhook.

    2. For URL, enter your notification URL. If you do not have a working URL yet, you can enter https://example.com as a placeholder.

    3. Optional. For API Version, choose a Square API version. By default, this is set to the same version as the application.

    4. For Events, choose inventory.count.updated. If you want to receive notifications about other events at the same webhook URL, choose them here or configure another endpoint.

    5. Choose Save.

    Note

    In the Production environment, ignore the Enable Webhooks setting on the Webhooks page. This setting applies to webhooks for Connect v1 APIs (deprecated).

To validate your webhook configuration

You can send a generic notification from the Developer Dashboard to validate that your webhook is configured correctly.

  1. On the Webhooks page for your application, choose the webhook that you want to test.

  2. In the Endpoint Details pane, choose More, and then choose Send Test Event.

  3. Select an event and then choose Send. If the endpoint is configured correctly, the Send Test Event dialog displays the response code and notification body.

Receive inventory event notifications Permalink Get a link to this section

To handle notifications, applications typically perform the following steps:

  1. Validate the authenticity of the notification. For more information, see Validate Notifications.

  2. Respond with an HTTP 2xx response code within 10 seconds of receiving the notification. For more information, see Notification Delivery SLA.

  3. Inspect, process, store, or forward the notification.

The body of the notification is a JSON object that contains the following properties.

PropertyDescription
merchant_idThe ID of the seller associated with the inventory count.
location_idThe ID of the seller location where the inventory is stored.
typeThe type of event: inventory.count.updated
event_idThe unique ID of the inventory event, which is used for idempotency support.
created_atA timestamp of when the event occurred (for example: 2020-12-28T21:59:15.286Z).
dataInformation about the inventory count change, represented by the following object: InventoryCountUpdatedWebhookData.

Test your webhooks Permalink Get a link to this section

To test your webhook with actual resources, change an inventory quantity of an item variation in your account. Make sure to test with the same environment (Sandbox or Production) where you registered for the webhook.

The following are some ways you can trigger inventory event notifications.

Test from the Seller Dashboard

  1. Open the Seller Dashboard.

  2. From the navigation pane, choose Items, then select an item to open the Edit Item sheet, click on stock, turn on tracking if it is not already on, select an adjustment reason, and update the stock count.

Test from API Explorer

Sign in to API Explorer and choose your Sandbox or Production environment. Call the Inventory API BatchChangeInventory endpoint as needed to test your webhook.

Test using cURL

Send cURL requests to the Inventory API endpoint. For more information, see Build and Manage a Simple Inventory.

Note

You can also send a generic test notification from the Developer Dashboard.

You should receive notifications for inventory events that you subscribe to. Square does not send notifications for events that fail.

For information about troubleshooting Square webhooks, see Troubleshoot Webhooks.