POST

Receive recovery claim from external system

POST

https://api.metahvac.com

/webhooks/warranties/v1.0/{source}/recovery-claims

Receives recovery claim data from external warranty systems (currently Trane). A recovery claim occurs when a supplier (Trane) identifies that METUS supplied a defective part and needs to be debited for repair costs. This endpoint validates the claim, maps distributor/owner IDs based on the source system, and queues the claim for background processing in Salesforce. The endpoint returns 202 Accepted immediately after validation, and the actual Salesforce integration happens asynchronously.

Receive recovery claim from external system › path Parameters

source

string · enum · required

The source system identifier. Determines how distributor/owner IDs are resolved. Currently only 'trane' is supported.

Enum values:

trane

Receive recovery claim from external system › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Receive recovery claim from external system › Request Body

recoveryClaimNumber

string · required

Unique identifier for the recovery claim in the source system.

warrantyClaimNumber

string · required

Reference to the original warranty claim that this recovery claim is associated with.

sku

string · required

SKU/model number of the unit that failed.

serialNumber

string · required

Serial number of the unit that failed.

debitAmount

integer · min: 0 · required

Total amount to be debited for this recovery claim in cents (e.g., 45000 = $450.00). Cannot be negative. Follows the Stripe pattern for currency representation.

submittedDate

string · date-time

Date when the recovery claim was submitted (RFC3339 timestamp).

approvedOnDate

string · date-time

Date when the recovery claim was approved (RFC3339 timestamp).

accountNumber

string

Account number in the source system.

dealerId

string

Dealer/contractor identifier.

dealerState

string

State where the dealer is located.

dealerCity

string

City where the dealer is located.

installDate

string · date-time

Date when the unit was installed (RFC3339 timestamp).

failureDate

string · date-time

Date when the unit failure occurred (RFC3339 timestamp).

repairDate

string · date-time

Date when the repair was completed (RFC3339 timestamp).

faultLocation

string

Description of where the fault occurred in the unit.

object[]

Parts that were installed during the warranty repair. At least one installedParts or recoverableParts entry is required.

object[]

Parts for which we can charge back the supplier for warranty costs. At least one installedParts or recoverableParts entry is required.

originalSourceId

string

Source system identifier used to map to internal distributor/owner IDs. For Trane: 'CS' = Control Systems, 'GP' = Gulfport, 'DS' or other = Default/Distribution.

Receive recovery claim from external system › Responses

Recovery claim accepted for processing. The claim has passed initial validation and has been queued for background processing. The actual Salesforce integration will happen asynchronously.

success

boolean

object

object[]

POST/webhooks/warranties/v1.0/{source}/recovery-claims

curl https://api.metahvac.com/webhooks/warranties/v1.0/:source/recovery-claims \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "recoveryClaimNumber": "RC2025-12345",
  "submittedDate": "2025-01-15T10:30:00Z",
  "approvedOnDate": "2025-01-20T14:00:00Z",
  "warrantyClaimNumber": "WC2024-98765",
  "accountNumber": "ACC-123456",
  "dealerId": "DEALER-789",
  "dealerState": "CA",
  "dealerCity": "Los Angeles",
  "sku": "PUZ-A36NKA7",
  "serialNumber": "ABCD1234",
  "installDate": "2023-06-15T00:00:00Z",
  "failureDate": "2024-12-10T00:00:00Z",
  "repairDate": "2024-12-15T00:00:00Z",
  "faultLocation": "Compressor",
  "installedParts": [
    {
      "partNumber": "PART-12345",
      "quantity": 1
    }
  ],
  "recoverableParts": [
    {
      "partNumber": "PART-67890",
      "quantity": 1,
      "costPerUnit": 25000
    }
  ],
  "debitAmount": 45000,
  "originalSourceId": "CS"
}'

Example Request Body

{
  "recoveryClaimNumber": "RC2025-12345",
  "submittedDate": "2025-01-15T10:30:00Z",
  "approvedOnDate": "2025-01-20T14:00:00Z",
  "warrantyClaimNumber": "WC2024-98765",
  "accountNumber": "ACC-123456",
  "dealerId": "DEALER-789",
  "dealerState": "CA",
  "dealerCity": "Los Angeles",
  "sku": "PUZ-A36NKA7",
  "serialNumber": "ABCD1234",
  "installDate": "2023-06-15T00:00:00Z",
  "failureDate": "2024-12-10T00:00:00Z",
  "repairDate": "2024-12-15T00:00:00Z",
  "faultLocation": "Compressor",
  "installedParts": [
    {
      "partNumber": "PART-12345",
      "quantity": 1
    }
  ],
  "recoverableParts": [
    {
      "partNumber": "PART-67890",
      "quantity": 1,
      "costPerUnit": 25000
    }
  ],
  "debitAmount": 45000,
  "originalSourceId": "CS"
}

json

Example Responses

{
  "success": true,
  "data": {
    "message": "Recovery claim accepted for processing",
    "source": "trane",
    "recoveryClaimNumber": "RC2025-12345",
    "warrantyClaimNumber": "WC2024-98765",
    "debitAmount": 45000,
    "acceptedAt": "2025-01-20T14:05:30Z"
  },
  "errors": []
}

json

application/json

Send debit confirmation to Trane

POST

https://api.metahvac.com

/webhooks/warranties/v1.0/trane/debit-confirmations

Sends debit memo confirmation to Trane to close out recovery claims. After METUS has issued a debit memo for an approved recovery claim, Cadence (or Salesforce workflows) calls this endpoint with the debit details. The endpoint validates the payload and forwards it to Trane's system to complete the recovery claim lifecycle. This is the final step in the recovery claim process, notifying Trane that we've officially debited them for the warranty recovery costs.

Send debit confirmation to Trane › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Send debit confirmation to Trane › Request Body

Request payload for sending a debit confirmation to Trane

DebitConfirmationRequest

recoveryClaimNumber

string · required

The recovery claim number that this debit memo is associated with. Must match a previously submitted recovery claim.

claimNumber

string · required

Trane's warranty claim number that this recovery claim is associated with.

debitMemoNumber

string · required

The debit memo number issued by METUS for this recovery claim.

debitMemoDate

string · date-time · required

The date when the debit memo was issued (RFC3339 timestamp).

approvedDebitAmount

integer · min: 0 · required

Total approved debit amount in cents (e.g., 8710 = $87.10). Follows the Stripe pattern for currency representation.

Send debit confirmation to Trane › Responses

Debit confirmation successfully sent to Trane.

success

boolean

data

null

object[]

POST/webhooks/warranties/v1.0/trane/debit-confirmations

curl https://api.metahvac.com/webhooks/warranties/v1.0/trane/debit-confirmations \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "recoveryClaimNumber": "RC2025-12345",
  "claimNumber": "WC2024-98765",
  "debitMemoNumber": "DM-2025-67890",
  "debitMemoDate": "2025-02-01T10:00:00Z",
  "approvedDebitAmount": 8710
}'

Example Request Body

{
  "recoveryClaimNumber": "RC2025-12345",
  "claimNumber": "WC2024-98765",
  "debitMemoNumber": "DM-2025-67890",
  "debitMemoDate": "2025-02-01T10:00:00Z",
  "approvedDebitAmount": 8710
}

json

Example Responses

{
  "success": true,
  "data": null,
  "errors": []
}

json

application/json