Liabilities API¶

The Liabilities API provides endpoints for partners using the Credit Line payment model to view their credit utilization and liability records.

Overview¶

Partners operating on a Credit Line basis can use these endpoints to:

Monitor their current credit utilization
View individual liability records
List all liabilities with filtering and pagination

Endpoints¶

GET /api/liabilities/utilization¶

Get the current credit line utilization for your partner account.

Authentication: Required (X-Api-Key)

Example Request

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/liabilities/utilization"

Responses:

200 OK: Utilization data returned successfully
401 Unauthorized: Invalid/missing API key
429 Too Many Requests: Rate limit exceeded

Response Schema (200 OK)

Field	Type	Description
`partnerId`	string	Unique identifier for the partner (UUID format).
`balance`	number	Current account balance.
`collateralDeposit`	number	Collateral deposit amount held by the partner.
`creditRatioMultiplier`	number	Multiplier applied to the collateral deposit to determine credit limit.
`creditLimit`	number	Maximum credit limit (`collateralDeposit × creditRatioMultiplier`).
`usedCredit`	number	Sum of all unpaid liability amounts (Pending + Overdue).
`remainingCredit`	number	Credit still available (`creditLimit - usedCredit`, minimum 0).
`spendingPower`	number	Total amount available for new bookings (`remainingCredit + balance`).
`amountDue`	number	Total amount due from unpaid invoices.
`utilizationPercentage`	number	Percentage of credit limit currently utilized (0–100).
`isBlocked`	boolean	Whether the partner is blocked from making new bookings (utilization ≥ 100%).

Example Response

{
  "partnerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "balance": 50000.00,
  "collateralDeposit": 50000.00,
  "creditRatioMultiplier": 1.5,
  "creditLimit": 75000.00,
  "usedCredit": 25000.00,
  "remainingCredit": 50000.00,
  "spendingPower": 100000.00,
  "amountDue": 0.00,
  "utilizationPercentage": 33.33,
  "isBlocked": false
}

GET /api/liabilities/{liabilityId}¶

Get details of a specific liability by its ID.

Authentication: Required (X-Api-Key)

Path Parameters:

Parameter	Type	Required	Description
`liabilityId`	string (GUID)	Yes	Unique identifier for the liability

Example Request

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/liabilities/f06c23b3-666f-4246-a11f-d37d828422fc"

Responses:

200 OK: Liability details returned successfully
401 Unauthorized: Invalid/missing API key
403 Forbidden: Liability does not belong to this partner
404 Not Found: Liability not found
429 Too Many Requests: Rate limit exceeded

Response Schema (200 OK)

Field	Type	Description
`id`	string	Unique identifier for the liability (UUID format).
`partnerId`	string	Partner ID this liability belongs to.
`requestId`	string	Original request ID that created this liability.
`orderId`	string	Associated order ID.
`bookingReference`	string	Booking reference number.
`amount`	number	Liability amount.
`effectiveDate`	string	Date when the liability becomes effective (ISO 8601 format).
`paymentWindowStart`	string	Start of the payment window (ISO 8601 format).
`paymentWindowEnd`	string	End of the payment window (ISO 8601 format).
`status`	string	Current status: `Pending`, `Paid`, or `Overdue`.
`description`	string	Description of the liability.
`createdDate`	string	Date when the liability was created (ISO 8601 format).
`createdByUserEmail`	string	Email of the user who created the liability.
`paidDate`	string	Date when the liability was paid (ISO 8601 format, if applicable).
`paidByUserEmail`	string	Email of the user who marked the liability as paid (if applicable).
`utilizationAtCreation`	number	Credit utilization percentage at the time the liability was created.

Example Response

{
  "id": "f06c23b3-666f-4246-a11f-d37d828422fc",
  "partnerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "requestId": "req-12345",
  "orderId": "ord-67890",
  "bookingReference": "BK-2025-001234",
  "amount": 1250.00,
  "effectiveDate": "2025-01-15T00:00:00Z",
  "paymentWindowStart": "2025-01-10T00:00:00Z",
  "paymentWindowEnd": "2025-01-20T00:00:00Z",
  "status": "Pending",
  "description": "Hotel booking liability",
  "createdDate": "2025-01-05T14:30:00Z",
  "createdByUserEmail": "system",
  "paidDate": null,
  "paidByUserEmail": null,
  "utilizationAtCreation": 25.5
}

GET /api/liabilities¶

Get a paginated list of liabilities for your partner account.

Authentication: Required (X-Api-Key)

Query Parameters:

Parameter	Type	Required	Description
`status`	string	No	Filter by status: `Pending`, `Paid`, or `Overdue`
`offset`	integer	No	Number of records to skip (default: 0)
`limit`	integer	No	Maximum number of records to return (default: 50)

Example Request

# Get all liabilities
curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/liabilities"

# Get pending liabilities with pagination
curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/liabilities?status=Pending&offset=0&limit=25"

Responses:

200 OK: Liabilities list returned successfully
401 Unauthorized: Invalid/missing API key
429 Too Many Requests: Rate limit exceeded

Response Schema (200 OK)

Field	Type	Description
`totalCount`	integer	Total number of liabilities matching the query.
`liabilities`	array	Array of liability objects.

Each liability object in the array follows the same schema as the single liability response above.

Example Response

{
  "totalCount": 42,
  "liabilities": [
    {
      "id": "f06c23b3-666f-4246-a11f-d37d828422fc",
      "partnerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "requestId": "req-12345",
      "orderId": "ord-67890",
      "bookingReference": "BK-2025-001234",
      "amount": 1250.00,
      "effectiveDate": "2025-01-15T00:00:00Z",
      "paymentWindowStart": "2025-01-10T00:00:00Z",
      "paymentWindowEnd": "2025-01-20T00:00:00Z",
      "status": "Pending",
      "description": "Hotel booking liability",
      "createdDate": "2025-01-05T14:30:00Z",
      "createdByUserEmail": "system",
      "paidDate": null,
      "paidByUserEmail": null,
      "utilizationAtCreation": 25.5
    }
  ]
}

Liability Statuses¶

Status	Description
`Pending`	Liability is awaiting payment within the payment window.
`Paid`	Liability has been paid and settled.
`Overdue`	Payment window has passed without payment.

Credit Line Concepts¶

Credit Limit¶

The credit limit is derived from the collateral deposit and the credit ratio multiplier:

Credit Limit = Collateral Deposit × Credit Ratio Multiplier

Utilization¶

Credit utilization is calculated as:

Utilization % = (Used Credit / Credit Limit) × 100

Remaining Credit & Spending Power¶

Remaining credit and spending power determine how much more can be booked:

Remaining Credit = Credit Limit - Used Credit
Spending Power   = Remaining Credit + Balance

Blocking¶

When utilization reaches 100%, the partner is blocked from making new bookings until liabilities are paid.

Best Practices¶

Monitor utilization regularly: Check your utilization to avoid booking disruptions
Pay within the payment window: Avoid overdue status by paying liabilities on time
Track individual liabilities: Use the list endpoint to reconcile bookings with liabilities
Plan for peak periods: Ensure sufficient credit availability during high-booking periods