Check Exempt/Deemed Taxpayer (T137)

Verify whether a taxpayer is eligible for tax exemptions or deemed VAT status for specific commodity categories. This endpoint returns taxpayer exemption status, project details, and applicable tax treatments. Requires encrypted request and response.

---

Endpoint Overview

Property	Value
Interface Code	T137
Request Encrypted	✅ Yes
Response Encrypted	✅ Yes
Request Body	{ "tin": "...", "commodityCategoryCode": "..." }
Response Format	JSON

---

Flow Description

1. Client submits taxpayer TIN and optional commodity category codes.
2. Server validates taxpayer status and exemption registrations.
3. Server returns:
   • Taxpayer type (normal, exempt, deemed, or both)
   • Exemption type (VAT, Excise Duty, or both)
   • Commodity category-specific taxpayer types
   • Deemed/exempt project list with details (project ID, name, codes, limits)
4. Client uses response to determine applicable tax treatments for invoices.

💡 Tip: Call this endpoint before issuing invoices to determine if special tax treatments (exempt, deemed, zero-rated) apply to specific transactions.

---

PHP

try {
    // Call T137: Check Exempt/Deemed Taxpayer
    $response = $client->checkTaxpayerType(
        tin: '1000029771',
        commodityCategoryCode: '10000000,10000001'
    );
    
    $content = $response['data']['content'] ?? $response;
    $taxpayerType = $content['taxpayerType'] ?? null;
    
    if ($taxpayerType) {
        echo "✅ Taxpayer Type: {$taxpayerType}\n";
        
        // Map taxpayer type
        $typeMap = [
            '101' => 'Normal Taxpayer',
            '102' => 'Exempt Taxpayer',
            '103' => 'Deemed Taxpayer',
            '104' => 'Both (Deemed & Exempt)'
        ];
        echo "   Status: " . ($typeMap[$taxpayerType] ?? 'Unknown') . "\n";
        
        // Check exemption type
        if (isset($content['exemptType'])) {
            $exemptMap = [
                '101' => 'VAT Exemption',
                '102' => 'Excise Duty Exemption',
                '103' => 'Both VAT & Excise Duty'
            ];
            echo "   Exemption: " . ($exemptMap[$content['exemptType']] ?? 'None') . "\n";
        }
        
        // Check project list
        if (isset($content['deemedAndExemptProjectList'])) {
            foreach ($content['deemedAndExemptProjectList'] as $project) {
                echo "   Project: {$project['projectName']} ({$project['deemedExemptCode']})\n";
            }
        }
    }
    
} catch (\UraEfrisSdk\Exceptions\APIException $e) {
    echo "❌ Check failed: " . $e->getMessage() . "\n";
    echo "   Return Code: " . $e->getReturnCode() . "\n";
}

JavaScript / TypeScript

try {
    // Call T137: Check Exempt/Deemed Taxpayer
    const response = await client.checkTaxpayerType(
        '1000029771',                    // tin
        '10000000,10000001'              // commodityCategoryCode
    );
    
    const content = response?.data?.content ?? response;
    const taxpayerType = content?.taxpayerType;
    
    if (taxpayerType) {
        console.log('✅ Taxpayer Type:', taxpayerType);
        
        // Map taxpayer type
        const typeMap: Record<string, string> = {
            '101': 'Normal Taxpayer',
            '102': 'Exempt Taxpayer',
            '103': 'Deemed Taxpayer',
            '104': 'Both (Deemed & Exempt)'
        };
        console.log('   Status:', typeMap[taxpayerType] || 'Unknown');
        
        // Check exemption type
        if (content?.exemptType) {
            const exemptMap: Record<string, string> = {
                '101': 'VAT Exemption',
                '102': 'Excise Duty Exemption',
                '103': 'Both VAT & Excise Duty'
            };
            console.log('   Exemption:', exemptMap[content.exemptType] || 'None');
        }
        
        // Check project list
        if (content?.deemedAndExemptProjectList) {
            content.deemedAndExemptProjectList.forEach((project: any) => {
                console.log(`   Project: ${project.projectName} (${project.deemedExemptCode})`);
            });
        }
        
        return content;
    } else {
        console.warn('⚠️  Could not retrieve taxpayer type');
        return null;
    }
    
} catch (error: any) {
    console.error(`❌ Check failed: ${error.message}`);
    if (error.returnCode) {
        console.error(`   Return Code: ${error.returnCode}`);
    }
    throw error;
}

Python

try:
    # Call T137: Check Exempt/Deemed Taxpayer
    response = client.check_taxpayer_type(
        tin='1000029771',
        commodity_category_code='10000000,10000001'
    )
    
    content = response.get("data", {}).get("content", response)
    taxpayer_type = content.get("taxpayerType")
    
    if taxpayer_type:
        print("✅ Taxpayer Type:", taxpayer_type)
        
        # Map taxpayer type
        type_map = {
            '101': 'Normal Taxpayer',
            '102': 'Exempt Taxpayer',
            '103': 'Deemed Taxpayer',
            '104': 'Both (Deemed & Exempt)'
        }
        print("   Status:", type_map.get(taxpayer_type, 'Unknown'))
        
        # Check exemption type
        if content.get("exemptType"):
            exempt_map = {
                '101': 'VAT Exemption',
                '102': 'Excise Duty Exemption',
                '103': 'Both VAT & Excise Duty'
            }
            print("   Exemption:", exempt_map.get(content["exemptType"], 'None'))
        
        # Check project list
        if content.get("deemedAndExemptProjectList"):
            for project in content["deemedAndExemptProjectList"]:
                print(f"   Project: {project['projectName']} ({project['deemedExemptCode']})")
        
    else:
        print("⚠️  Could not retrieve taxpayer type")
    
except Exception as e:
    print(f"❌ Check failed: {e}")
    if hasattr(e, "return_code"):
        print(f"   Return Code: {e.return_code}")
    raise

---

Request Structure

{
  "data": {
    "content": "BASE64_ENCRYPTED_PAYLOAD",
    "signature": "JKQWJK34K32JJEK2JQWJ5678",
    "dataDescription": {
      "codeType": "1",
      "encryptCode": "2",
      "zipCode": "0"
    }
  },
  "globalInfo": {
    "interfaceCode": "T137",
    "appId": "AP04",
    "version": "1.1.20191201",
    "tin": "1000029771",
    "deviceNo": "TCS9e0df01728335239",
    "taxpayerID": "1"
  }
}

Request Fields (Encrypted Payload)

Field	Required	Type	Length	Description
tin	✅ Yes	String	≤20	Taxpayer Identification Number to check
commodityCategoryCode	❌ No	String	≤18	Commodity category codes (multiple separated by commas, e.g., "10000000,10000001")

---

Response Structure

{
  "data": {
    "content": {
      "taxpayerType": "101",
      "exemptType": "101",
      "commodityCategory": [
        {
          "commodityCategoryCode": "10000000",
          "commodityCategoryTaxpayerType": "101"
        }
      ],
      "deemedAndExemptProjectList": [
        {
          "projectId": "10000000",
          "projectName": "Strategic Investment Project",
          "deemedExemptCode": "101",
          "commodityCategoryCode": "10000000",
          "serviceMark": "102",
          "unit": "101",
          "currentQty": "100",
          "currentAmount": "100",
          "currency": "USD",
          "exchangeRateDate": "2025-06-12",
          "currentAmountCurrency": "100"
        }
      ]
    }
  },
  "globalInfo": {
    "interfaceCode": "T137",
    "returnStateInfo": {
      "returnCode": "00",
      "returnMessage": "SUCCESS"
    }
  }
}

---

Response Fields

Taxpayer Status

Field	Required	Type	Description
taxpayerType	✅ Yes	String (3)	101=Normal, 102=Exempt, 103=Deemed, 104=Both (Deemed & Exempt)
exemptType	❌ No	String (3)	101=VAT Exemption, 102=Excise Duty Exemption, 103=Both VAT & Excise Duty

Commodity Category Array

Field	Required	Type	Description
commodityCategoryCode	✅ Yes	String (18)	Commodity category identifier
commodityCategoryTaxpayerType	✅ Yes	String (3)	Taxpayer type for this specific category (101-104)

Deemed/Exempt Project List Array

Field	Required	Type	Description
projectId	✅ Yes	String (18)	Unique project identifier
projectName	✅ Yes	String (100)	Project name/description
deemedExemptCode	✅ Yes	String (3)	Exemption type code (see codes below)
commodityCategoryCode	✅ Yes	String (18)	Associated commodity category
serviceMark	✅ Yes	String (3)	101=Yes (service), 102=No (goods)
unit	✅ Yes	String (3)	Unit of measure from T115 rateUnit
currentQty	❌ No	Number	Current quantity limit/usage
currentAmount	❌ No	Number	Current amount limit/usage
currency	✅ Yes	String (10)	Currency code (e.g., UGX, USD)
exchangeRateDate	✅ Yes	Date	Exchange rate date (yyyy-MM-dd)
currentAmountCurrency	✅ Yes	Number	Amount in specified currency

Deemed/Exempt Code Values

Code	Description
101	Strategic Investor
102	Petroleum Licensee
103	Aid Funded Project Contractor
104	Government MDA (Ministry/Department/Agency)
105	VAT & Excise Duty Exempt
106	Excise Duty Exempt
107	Mining Licensee
108	EACOP Licensee
109	EACOP Level 1 Contractor

---

Return Codes

Code	Message	Description
00	SUCCESS	Taxpayer status retrieved successfully
99	Unknown error	Generic server error
400	Device does not exist	deviceNo not registered for this TIN
402	Device key expired	Device credentials expired; re-run T102
403	Device status is abnormal	Device blocked or suspended
2110	tin cannot be empty!	Missing TIN in request
2111	tin:Byte length cannot be greater than 20!	TIN exceeds maximum length
2261	The taxpayer does not exist or the state is abnormal!	TIN not found or inactive
3060	The TIN is not registered in the ETAX system	TIN not in eTax database
3063	Your tin does not exist.	TIN not found
3064	The status of TIN is abnormal.	TIN suspended or deregistered

💡 Tip: A taxpayerType of 101 (Normal) means no special exemptions apply. Types 102, 103, or 104 indicate special tax treatments that must be applied to invoices.

---

Common Use Cases

1. Pre-Invoice Validation
   Check taxpayer exemption status before issuing invoices to apply correct tax treatments (exempt, deemed, zero-rated).

2. Project-Based Exemptions
   Verify specific project exemptions (e.g., EACOP, Mining, Strategic Investor) for commodity-specific tax treatments.

3. Commodity-Specific Tax Treatment
   Determine if certain commodity categories have different taxpayer types for the same TIN.

4. Compliance Auditing
   Log exemption status checks for audit trails and compliance reporting.

5. Multi-Project Management
   Handle taxpayers with multiple exemption projects simultaneously (e.g., both Strategic Investor and Government MDA).

---

Integration Checklist

✅ Validate TIN format before calling T137
✅ Store taxpayerType and exemptType for session duration
✅ Check deemedAndExemptProjectList for project-specific limits
✅ Apply correct deemedExemptCode to invoice goods details
✅ Re-check exemption status periodically (may change)
✅ Handle 101 (Normal) as default when no exemptions apply