Inventory API

Query URA's goods catalog and manage your product mappings. The inventory API provides access to EFRIS master data and your Smart Registry mappings.

Overview

The Inventory API serves two main purposes: querying URA's official goods catalog and managing your product mappings that power the Smart Registry.

Goods Catalog

Query URA's master database of goods, services, and commodities to ensure compliance and get the latest codes.

Product Mappings

Create and manage mappings between your SKUs and URA goods codes, including unit conversions and tax configurations.

Query Goods Catalog

Search URA's master goods catalog to find the correct codes and details for your products. This data is cached and updated regularly.

GET /v1/catalog/products

# Request

curl "https://api.taxbridge.com/v1/catalog/products?taxpayerId=your_id&pageNo=1&pageSize=20" \
  -H "Authorization: Bearer sk_test_1234567890abcdef"

200 OK Response

{
  "result": {
    "totalRecords": 1250,
    "pageNo": 1,
    "pageSize": 20,
    "goodsList": [
      {
        "goodsCode": "204024000000",
        "goodsName": "Organic Processed Clean Chia",
        "categoryCode": "30111601",
        "unit": "KGM",
        "exciseFlag": "2"
      }
    ]
  }
}

Create Product Mapping

Map your internal SKU to a URA goods code. This enables automatic normalization during invoice creation.

POST /v1/product-maps

# Request

curl -X POST https://api.taxbridge.com/v1/product-maps \
  -H "Authorization: Bearer sk_test_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "externalRef": "CHIA-50KG",
    "uraCode": "204024000000",
    "goodsName": "Organic Processed Clean Chia",
    "measureUnit": "BAG",
    "pieceUnit": "KGM",
    "pieceScalingFactor": 50,
    "exportUnit": "TNE",
    "exportScalingFactor": 0.05
  }'

201 Created Response

{
  "id": "pm_abc123",
  "externalRef": "CHIA-50KG",
  "uraCode": "204024000000",
  "status": "active",
  "created_at": "2025-12-10T10:00:00Z"
}

Get Product Mapping

Retrieve details of a specific product mapping by ID.

GET /v1/product-maps/{id}

# Request

curl https://api.taxbridge.com/v1/product-maps/pm_abc123 \
  -H "Authorization: Bearer sk_test_1234567890abcdef"

200 OK Response

{
  "id": "pm_abc123",
  "externalRef": "CHIA-50KG",
  "uraCode": "204024000000",
  "goodsName": "Organic Processed Clean Chia",
  "measureUnit": "BAG",
  "pieceUnit": "KGM",
  "pieceScalingFactor": 50,
  "exportUnit": "TNE",
  "exportScalingFactor": 0.05,
  "exciseFlag": "2",
  "updated_at": "2025-12-10T10:00:00Z"
}

List Product Mappings

Get all product mappings for your account with optional filtering.

GET /v1/product-maps

# Request

curl "https://api.taxbridge.com/v1/product-maps?limit=50&status=active" \
  -H "Authorization: Bearer sk_test_1234567890abcdef"

200 OK Response

{
  "data": [
    {
      "id": "pm_abc123",
      "externalRef": "CHIA-50KG",
      "uraCode": "204024000000",
      "status": "active"
    }
  ],
  "has_more": true,
  "total_count": 150
}

Update Product Mapping

Modify an existing product mapping. Useful for updating unit conversions or correcting goods codes.

PATCH /v1/product-maps/{id}

# Request

curl -X PATCH https://api.taxbridge.com/v1/product-maps/pm_abc123 \
  -H "Authorization: Bearer sk_test_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "pieceScalingFactor": 55
  }'

200 OK Response

{
  "id": "pm_abc123",
  "externalRef": "CHIA-50KG",
  "pieceScalingFactor": 55,
  "updated_at": "2025-12-10T10:30:00Z"
}

Request Parameters

Query Goods Catalog

Parameter	Type	Required	Description
taxpayerId	string	Yes	Taxpayer ID for the query
queryType	number	No	0=full, 1=incremental, 2=agent/stock
pageNo	number	No	Page number (default: 1)
pageSize	number	No	Items per page (default: 20)

Create Product Mapping

Parameter	Type	Required	Description
externalRef	string	Yes	Your internal SKU identifier
uraCode	string	Yes	URA goods code (9-12 digits)
goodsName	string	Yes	Official goods name from URA
measureUnit	string	Yes	Selling unit (e.g., "BAG", "KGM")
pieceUnit	string	No	Inventory unit (usually "KGM")
pieceScalingFactor	number	No	Pieces per selling unit
exportUnit	string	No	Export unit (e.g., "TNE")
exportScalingFactor	number	No	Export units per selling unit

Error Responses

400 Bad Request

Invalid URA code format or missing required fields.

{"error": "ValidationError", "message": "Invalid URA code format"}

409 Conflict

SKU already mapped to a different goods code.

{"error": "Conflict", "message": "SKU already exists"}

422 Unprocessable Entity

URA code not found in catalog or scaling factors invalid.

{"error": "ValidationError", "message": "Goods code not found"}

Best Practices

1

Validate Before Mapping

Always query the goods catalog first to ensure the URA code exists and get the correct goods name.

2

Use Consistent Units

Standardize your measureUnit across similar products (e.g., always use "KGM" for weight-based items).

3

Test Scaling Factors

Verify that pieceScalingFactor and exportScalingFactor produce correct quantities in test invoices.