# receiveItemChangeWebhook

Receive item-level tariff and invalid HS code change webhook notifications.

`POST /nomenclature/webhook/item-changes`

**API:** Avalara Item Classification API
**Tag:** NomenclatureChangeWebhook
**API Version:** 16.0.1-oas3
**Base URL:** https://api-sandbox.classification.avalara.net
**Authentication:** Basic (username + license key) or Bearer token

Source: https://developer.avalara.com/products/managed-and-premium-tariff-code/api/methods/NomenclatureChangeWebhook/receiveItemChangeWebhook/

## Description

This endpoint receives item-level changes for a catalog that match configured category or item-code filters. The payload uses a flat envelope with item identity carried inline on each change. Each change is either a TARIFF_CHANGE for a reclassification where the hsCode is the new code, or an INVALID_HSCODE for a retired or expired code. Return an HTTP 2xx response to acknowledge receipt. Avalara does not retry 4xx responses, but retries 5xx responses and timeouts.

## Request Body

**Content-Type:** `application/json`
**Schema:** `ItemChangeNotification`

Defines the item-level notification. The payload uses a flat `changes[]` envelope where item identity is carried inline on each change. The `eventType` value is either `TARIFF_CHANGE` or `INVALID_HSCODE`.

| Property | Type | Required | Description |
|---|---|---|---|
| `notificationId` | string | **Yes** | Provides the unique identifier for this notification. |
| `timestamp` | string | **Yes** | Provides the date and time the notification was sent, in ISO-8601 UTC format. |
| `detectedAt` | string | No | Provides the date and time when the underlying changes were detected, in ISO-8601 UTC format. This field is omitted when the detection time is unknown. |
| `customerId` | integer | **Yes** | Identifies the Avalara customer account associated with this notification. |
| `totalChanges` | integer | **Yes** | Provides the total number of item-level changes included in this notification. |
| `changesByType` | object | No | Provides the count of changes grouped by `eventType`. |
| `changes` | ItemChange[] | **Yes** | Lists the item-level changes included in this notification. |

## Responses

| Status | Description | Schema |
|---|---|---|
| 200 | Indicates that the notification was received and acknowledged. |  |
| 201 | Indicates that the notification was received and processed. |  |
| 202 | Indicates that the notification was accepted for asynchronous processing. |  |
| 204 | Indicates that the notification was acknowledged and returns no content. |  |
| 400 | Indicates a bad request where the payload was rejected by the client. Avalara does not retry this request. |  |

## Example Request

```bash
curl -X POST "https://api-sandbox.classification.avalara.net/nomenclature/webhook/item-changes" \
  -H "Authorization: Basic <credentials>" \
  -H "Accept: application/json" \
  -d '{
  "notificationId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-06-22T10:30:00Z",
  "detectedAt": "2026-06-22T09:15:42Z",
  "customerId": 123,
  "totalChanges": 2,
  "changesByType": {
    "TARIFF_CHANGE": 1,
    "INVALID_HSCODE": 1
  },
  "changes": [
    {
      "COD": "US",
      "hsCode": "8517130000",
      "eventType": "TARIFF_CHANGE",
      "companyId": 3402,
      "itemId": 99812345,
      "itemCode": "B07Z7Q62V3",
      "itemDescription": "Smartphone, 6.1 inch",
      "itemGroup": "Electronics & Photo"
    },
    {
      "COD": "DE",
      "hsCode": "6109100010",
      "eventType": "INVALID_HSCODE",
      "companyId": 3402,
      "itemId": 99812346,
      "itemCode": "SKU-123",
      "itemDescription": "Cotton t-shirt",
      "itemGroup": "Apparel"
    }
  ]
}'
```