Skip to main content

Update Buyer Details (T166)

Update buyer information on an existing invoice after issuance. This endpoint allows modification of buyer details (TIN, name, contact information, etc.) for invoices that have already been uploaded to the EFRIS system. Request is encrypted; response is unencrypted.

Endpoint Overview​

PropertyValue
Interface CodeT166
Request Encrypted✅ Yes
Response Encrypted❌ No
Request Body{ "invoiceNo": "...", "buyerTin": "...", ... }
Response FormatNULL (empty on success)

Flow Description​

  1. Client identifies invoice requiring buyer detail updates (typically EDC invoices).
  2. Client submits updated buyer information with original invoiceNo and createDateStr.
  3. Server validates invoice exists and buyer modification is allowed within permitted timeframe.
  4. Server updates buyer details and returns NULL response on success.
  5. Client confirms update completion and logs change for audit trail.

💡 Tip: Buyer details can only be modified within a limited period after invoice issuance (configurable via buyerModificationPeriod from T103). Credit notes cannot have buyer details modified.

try {
    // Call T166: Update Buyer Details
    $updateData = [
        'invoiceNo' => '321000229045',
        'buyerTin' => '1000029771',
        'buyerNinBrn' => '201905081705',
        'buyerPassportNum' => '',  // For foreigners only
        'buyerLegalName' => 'UGANDA REVENUE AUTHORITY',
        'buyerBusinessName' => 'UGANDA REVENUE AUTHORITY',
        'buyerAddress' => '198 NIP BUILDING Nakawa KAMPALA',
        'buyerEmailAddress' => 'services@ura.go.ug',
        'buyerMobilePhone' => '0772140000',
        'buyerLinePhone' => '0414123456',
        'buyerPlaceOfBusi' => 'KAMPALA NAKAWA DIVISION',
        'buyerType' => '0',  // 0=B2B, 1=B2C, 2=Foreigner
        'buyerCitizenship' => 'UG-Uganda',
        'buyerSector' => 'Government',
        'mvrn' => '',  // Motor Vehicle Registration Number (optional)
        'createDateStr' => '2025-02-19 10:21:00'
    ];
    
    $response = $client->updateBuyerDetails($updateData);
    
    // Response is NULL on success
    echo "✅ Buyer details updated successfully\n";
    echo "   Invoice: {$updateData['invoiceNo']}\n";
    echo "   Buyer TIN: {$updateData['buyerTin']}\n";
    echo "   Buyer Name: {$updateData['buyerLegalName']}\n";
    
} catch (\UraEfrisSdk\Exceptions\APIException $e) {
    echo "❌ Update failed: " . $e->getMessage() . "\n";
    echo "   Return Code: " . $e->getReturnCode() . "\n";
}

Request Structure​

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

Request Fields (Encrypted Payload)​

FieldRequiredTypeLengthDescription
invoiceNo✅ YesString≤20Original invoice number to update
buyerTin❌ NoString≤20Buyer TIN; required if buyerType=0 (B2B)
buyerNinBrn❌ NoString≤100Buyer NIN/BRN
buyerPassportNum❌ NoString≤20Passport number; required if buyerType=2 (Foreigner)
buyerLegalName❌ NoString≤256Buyer legal name
buyerBusinessName❌ NoString≤256Buyer business name
buyerAddress❌ NoString≤500Buyer physical address
buyerEmailAddress❌ NoString≤50Buyer email address (valid email format)
buyerMobilePhone❌ NoString≤30Buyer mobile phone number
buyerLinePhone❌ NoString≤30Buyer landline phone number
buyerPlaceOfBusi❌ NoString≤500Buyer place of business
buyerType✅ YesString (1)10=B2B, 1=B2C, 2=Foreigner
buyerCitizenship❌ NoString≤128Buyer citizenship (e.g., UG-Uganda)
buyerSector❌ NoString≤200Buyer sector (e.g., Government, Private)
buyerReferenceNo❌ NoString≤50Buyer reference number
mvrn❌ NoString≤32Motor Vehicle Registration Number (for fuel invoices)
createDateStr❌ NoString20Invoice creation timestamp (yyyy-MM-dd HH:mm:ss)

💡 Tip: At minimum, invoiceNo and buyerType are required. For B2B (buyerType=0), buyerTin cannot be empty. For Foreigners (buyerType=2), buyerPassportNum and buyerCitizenship are required.

Response Structure​

{
  "globalInfo": {
    "interfaceCode": "T166",
    "returnStateInfo": {
      "returnCode": "00",
      "returnMessage": "SUCCESS"
    }
  }
}

📋 Note: On success, the data.content is NULL or empty. Validation results are returned via globalInfo.returnStateInfo only.

Response Fields​

Global Info​

FieldRequiredTypeDescription
interfaceCode✅ YesString (5)Echoes T166
returnStateInfo✅ YesObjectContains returnCode and returnMessage

Return State Info​

FieldRequiredTypeDescription
returnCode✅ YesString00 = Success, otherwise error code
returnMessage✅ YesStringHuman-readable status message

Return Codes​

CodeMessageDescription
00SUCCESSBuyer details updated successfully
99Unknown errorGeneric server error
400Device does not existdeviceNo not registered for this TIN
402Device key expiredDevice credentials expired; re-run T102
403Device status is abnormalDevice blocked or suspended
2931invoiceNo: You can not modify buyer's information more than X timesMaximum modification limit exceeded
2932invoiceNo: The buyer information cannot be modified because of the fiscal document was generated * hours agoModification period expired
2973invoiceNo does not existInvoice number not found
3053Credit note is not allowed to modify the buyer's informationCannot modify credit note buyer details
3054The invoice has been issued credit note, can not modify buyer's informationOriginal invoice has credit note
3055The invoice has been applied for credit note, can not modify buyer's informationCredit note application in process
2110tin cannot be empty!Missing TIN when buyerType=0
2111tin: Byte length cannot be greater than 20!TIN exceeds maximum length
2244buyerDetails-->buyerType: cannot be empty!Missing buyer type
2245buyerDetails-->buyerType: Byte length cannot be greater than 3!Buyer type format error
3060The TIN is not registered in the ETAX systemBuyer TIN not found
3063Your tin does not existBuyer TIN not found
3064The status of TIN is abnormalBuyer TIN suspended or inactive

💡 Tip: Error 2932 is common—buyer details can only be modified within the configured buyerModificationPeriod (typically 48 hours from T103). Error 3053-3055 indicate credit note restrictions.

Common Use Cases​

  1. Invoice Buyer Correction
    Update incorrect buyer information on fuel station invoices after customer provides correct details.

  2. B2B Customer TIN Update
    Add or correct buyer TIN for business customers who initially purchased as B2C.

  3. Foreign Customer Documentation
    Update passport number and citizenship for foreign buyers after verification.

  4. Contact Information Updates
    Correct buyer email, phone numbers, or address for improved communication and record-keeping.

  5. Sector Classification Correction
    Update buyer sector (Government, Private, etc.) for accurate reporting and compliance.

  6. Motor Vehicle Registration
    Add MVRN for fuel invoices where vehicle registration is required for tracking.

Integration Checklist​

✅ Verify invoice exists via T108 before attempting buyer update
✅ Confirm invoice is not a credit note (T166 not allowed for credit notes)
✅ Check no credit note application is in process for the invoice
✅ Validate buyerType matches provided identification (TIN for B2B, passport for Foreigner)
✅ Ensure createDateStr is within allowed modification period from T103
✅ Validate email format for buyerEmailAddress field
✅ Verify buyer TIN exists in ETAX system via T119 before submission
✅ Log all buyer detail updates for audit trail compliance
✅ Handle NULL response gracefully (success = no content, check returnCode only)
✅ Re-query invoice via T108 after update to confirm changes applied