Item Master API

The Item Master API provides full CRUD operations for managing product master data, including HS code classification, verification, pending changes, and document management.

Required Scope: item_master:read, item_master:write, item_master:delete

List Items

Retrieve a paginated list of items with optional filters.


GET /api/v1/item-master

Query Parameters

Parameter	Type	Description
`search`	string	Search across `item_code`, `description`, `hs_code`, `sku`, `part_number`
`customer_id`	integer	Filter by customer ID
`status`	string	Filter by status: `active`, `inactive`, `pending`
`sort_by`	string	Sort field: `item_code`, `description`, `hs_code`, `status`, `created_at`, `updated_at` (default: `updated_at`)
`sort_order`	string	`asc` or `desc` (default: `desc`)
`per_page`	integer	Results per page (default: 15, max: 100)

Example Request


curl https://app.borderbolt.com/api/v1/item-master \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "status=active" \
  --data-urlencode "search=integrated circuit"

Example Response


{
  "data": [
    {
      "id": 801,
      "item_code": "PROD-001",
      "description": "Electronic Components - Integrated Circuits",
      "hs_code": "85423190",
      "country_of_origin": "CN",
      "status": "active",
      "net_weight": 0.84,
      "gross_weight": 0.90,
      "sku": "SKU-IC-001",
      "part_number": "AC-IC-1234",
      "unit_value": 10.00,
      "unit_currency": "EUR",
      "created_at": "2025-06-01T10:00:00.000000Z",
      "updated_at": "2026-03-20T14:30:00.000000Z",
      "verified_at": "2025-06-02T09:00:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 342
  }
}

Get Item

Retrieve a single item with all details, documents, and pending changes.


GET /api/v1/item-master/{id}


curl https://app.borderbolt.com/api/v1/item-master/801 \
  -H "Authorization: Bearer {token}"

Example Response


{
  "data": {
    "id": 801,
    "item_code": "PROD-001",
    "description": "Electronic Components - Integrated Circuits",
    "hs_code": "85423190",
    "taric_code": null,
    "country_of_origin": "CN",
    "preferential_origin": null,
    "status": "active",
    "net_weight": 0.84,
    "gross_weight": 0.90,
    "supplementary_units": null,
    "packaging_type": "CT",
    "packaging_marks": "LOT-A",
    "unit_value": 10.00,
    "unit_currency": "EUR",
    "duty_rate": 3.50,
    "vat_rate": 21.00,
    "licensing_required": false,
    "manufacturer_name": "Acme Electronics Ltd",
    "manufacturer_part_number": "AC-IC-1234",
    "sku": "SKU-IC-001",
    "part_number": "AC-IC-1234",
    "notes": "High-precision integrated circuits for industrial use",
    "created_at": "2025-06-01T10:00:00.000000Z",
    "updated_at": "2026-03-20T14:30:00.000000Z",
    "verified_at": "2025-06-02T09:00:00.000000Z",
    "pending_changes": [],
    "documents": [
      {
        "id": 5001,
        "type": "certificate_of_origin",
        "filename": "COO-PROD-001.pdf",
        "created_at": "2025-06-01T11:00:00.000000Z"
      }
    ]
  }
}

Search Items

Search active items by keyword. Returns up to 20 results — optimised for type-ahead lookups.


GET /api/v1/item-master/search

Query Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search keyword (matches `item_code`, `description`, `hs_code`)
`customer_id`	integer	No	Narrow search to a specific customer


curl https://app.borderbolt.com/api/v1/item-master/search \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "q=integrated"

Example Response


{
  "data": [
    {
      "id": 801,
      "item_code": "PROD-001",
      "description": "Electronic Components - Integrated Circuits",
      "hs_code": "85423190",
      "customer_id": null
    }
  ]
}

Create Item

Create a new item in the master catalog. Status defaults to active.


POST /api/v1/item-master

Request Body

Field	Required	Type	Description
`item_code`	Yes	string	Unique item code (max 100 chars)
`description`	Yes	string	Product description (max 500 chars)
`customer_id`	No	integer	Scope to a specific customer
`hs_code`	No	string	HS code (max 20 chars)
`taric_code`	No	string	TARIC additional code
`country_of_origin`	No	string	2-letter ISO country code
`preferential_origin`	No	string	2-letter ISO country code for preferential origin
`net_weight`	No	number	Net weight per unit (kg)
`gross_weight`	No	number	Gross weight per unit (kg)
`supplementary_units`	No	number	Supplementary units value
`unit_value`	No	number	Customs value per unit
`unit_currency`	No	string	Currency code (e.g. `EUR`)
`duty_rate`	No	number	Applicable duty rate (%)
`vat_rate`	No	number	Applicable VAT rate (%)
`licensing_required`	No	boolean	Whether an import/export licence is required
`packaging_type`	No	string	Packaging type code
`packaging_marks`	No	string	Package marks and numbers
`manufacturer_name`	No	string	Manufacturer name
`manufacturer_part_number`	No	string	Manufacturer part/article number
`sku`	No	string	SKU reference
`part_number`	No	string	Internal part number
`notes`	No	string	Internal notes

Example Request


curl -X POST https://app.borderbolt.com/api/v1/item-master \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "item_code": "PROD-002",
    "description": "Machinery Parts - Ball Bearings",
    "hs_code": "84821090",
    "country_of_origin": "DE",
    "net_weight": 0.15,
    "gross_weight": 0.18,
    "unit_value": 5.50,
    "unit_currency": "EUR",
    "manufacturer_name": "German Bearings GmbH"
  }'

Example Response


{
  "data": {
    "id": 802,
    "item_code": "PROD-002",
    "description": "Machinery Parts - Ball Bearings",
    "hs_code": "84821090",
    "status": "active",
    "created_at": "2026-03-25T10:00:00.000000Z"
  },
  "message": "Item created successfully"
}

HTTP 201 is returned on success. HTTP 422 is returned if item_code already exists for the same customer.

Update Item

Update an existing item.


PUT /api/v1/item-master/{id}

Same fields as Create Item, plus status (active, inactive, pending).

Classification Changes: Updating hs_code, taric_code, country_of_origin, or preferential_origin requires the item_master:write scope.


curl -X PUT https://app.borderbolt.com/api/v1/item-master/802 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "unit_value": 6.00,
    "notes": "Price updated per supplier notification"
  }'

Delete Item

Delete an item.


DELETE /api/v1/item-master/{id}


curl -X DELETE https://app.borderbolt.com/api/v1/item-master/802 \
  -H "Authorization: Bearer {token}"

Duplicate Item

Create a copy of an existing item. The new item gets _COPY appended to its item_code and must be verified again.


POST /api/v1/item-master/{id}/duplicate


curl -X POST https://app.borderbolt.com/api/v1/item-master/801/duplicate \
  -H "Authorization: Bearer {token}"

Example Response


{
  "data": {
    "id": 803,
    "item_code": "PROD-001_COPY",
    "description": "Electronic Components - Integrated Circuits",
    "status": "active",
    "verified_at": null,
    "created_at": "2026-03-25T15:00:00.000000Z"
  },
  "message": "Item duplicated successfully"
}

HTTP 201 is returned on success.

Verify Item

Mark an item as verified by a customs expert. Verification is recorded against the authenticated API user.


POST /api/v1/item-master/{id}/verify


curl -X POST https://app.borderbolt.com/api/v1/item-master/802/verify \
  -H "Authorization: Bearer {token}"

Example Response


{
  "data": {
    "id": 802,
    "item_code": "PROD-002",
    "status": "active",
    "verified_at": "2026-03-25T11:00:00.000000Z"
  },
  "message": "Item verified successfully"
}

Pending Changes

Retrieve classification change requests for an item.


GET /api/v1/item-master/{id}/pending-changes

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: `pending` (default), `approved`, `rejected`


curl https://app.borderbolt.com/api/v1/item-master/801/pending-changes \
  -H "Authorization: Bearer {token}"

Documents

List Documents


GET /api/v1/item-master/{id}/documents


curl https://app.borderbolt.com/api/v1/item-master/801/documents \
  -H "Authorization: Bearer {token}"

Status Values

Status	Description
`active`	Ready for use in declarations
`inactive`	Discontinued or archived
`pending`	Awaiting classification verification

Next Steps

Declaration Submit API — Use items in declarations
Declarations API — View item usage in declaration lines