---
name: early-payment-interest
description: >
  Instructs AI agents how to read Early Payment Interest Term configurations
  in Kyriba. These terms define the discount rates, fees, eligibility rules,
  and calendar settings for supply chain finance early payment programs.
version: 1.0.0
scopes:
  - workcap-early-payment-interest-terms-scope
authors:
  - kyriba
tags:
  - kyriba
  - working-capital
  - workcap
  - early-payment
  - api
---

> **Auth** — POST {AUTH_BASE_URL}/oauth/token · Basic base64(CLIENT_ID:CLIENT_SECRET) · no scope.
> Use token_type verbatim — do not hardcode `Bearer`. On 401: retry once with the other scheme (`token` vs `Bearer`). On 429: wait Kyriba-Customer-Rate-Limit-Reset.

# Kyriba API Skill: Early Payment Interest Terms

---

## Required Kyriba Permission

```
workcap-early-payment-interest-terms-scope
```

This is a Kyriba access permission — not an OAuth scope parameter. Do NOT add `scope=` to the token request.

---

## What are Early Payment Interest Terms?

Configuration objects that define the financial parameters for early payment programs in Working Capital. Each term specifies the funder, buyer, currency, maturity rate brackets, eligibility rules, and calculation settings.

> This API is **read-only**. Terms are configured in the Kyriba UI.

>  This API is part of the **Working Capital** module. Returns `404` if the module is not enabled.

---

##  Non-Standard Base URL

```
https://api.demo.kyriba.com/api/workcap/early-payment-interest-terms/v2
```

All endpoint paths are appended to this base.

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/workcap/early-payment-interest-terms/v2/early-payment-interest-terms` | List all terms |
| `GET` | `/api/workcap/early-payment-interest-terms/v2/early-payment-interest-terms/{uuid}` | Get a specific term |
| `GET` | `/api/workcap/early-payment-interest-terms/v2/early-payment-interest-terms/documented-fields` | List documented field names |
| `GET` | `/api/workcap/early-payment-interest-terms/v2/early-payment-interest-terms/documented-fields/{field}` | Get valid enum values |
| `GET` | `/api/workcap/early-payment-interest-terms/v2/early-payment-interest-terms/searchable-fields` | List filterable fields |

---

##  Non-Standard Pagination

Uses flat `offset` / `limit` - **NOT** `page.offset` / `page.limit`.

Response envelope uses standard `metadata` with `total`, `count`, `limit`, `offset`.

---

## Key Response Fields

| Field | Description |
|---|---|
| `uuid` | System identifier |
| `funder` | Financing funder `{ "uuid": "...", "code": "..." }` |
| `buyer` | Buyer company `{ "uuid": "...", "code": "..." }` |
| `currency` | Currency `{ "uuid": "...", "code": "EUR" }` |
| `programType` | e.g. `REVERSE_FACTORING` |
| `interestCalculationMethod` | e.g. `ANNUALIZED_RATE` |
| `interestBearer` | Who bears the interest: `SUPPLIER` or `BUYER` |
| `documentCategory` | e.g. `BUYER_MANAGED_PAYABLE` |
| `maturityRates[]` | Rate brackets - **not** `interestRates[]` |
| `maturityRates[].applicableStartDay` | Lower day bound - **not** `applyFrom` |
| `maturityRates[].applicableEndDay` | Upper day bound - **not** `applyTo` |
| `maturityRates[].markup1` | Primary interest rate / markup % |
| `maturityRates[].markup2` | Secondary markup % |
| `maturityRates[].markup3` | Tertiary markup % |
| `maturityRates[].discountCalculationMethod` | e.g. `SLIDING_SCALE` |
| `maturityRates[].minimalIndexEnabled` | Whether a minimum rate index is applied |
| `maturityRates[].minimalRate` | Minimum rate floor |
| `maturityRates[].maximalRate` | Maximum rate ceiling |
| `financingMode` | e.g. `CONVENTIONAL_FINANCING` |
| `dayType` | Day counting: `BUSINESS_DAYS` or `CALENDAR_DAYS` |
| `calculationBasis` | e.g. `30/360`, `ACT/365` |
| `interestFormula` | e.g. `FORMULA_1` |
| `provideFinancingAfterDays` | Minimum days after invoice before early payment |
| `untilDaysCounting` | Reference point: `DUE_DATE` or `INVOICE_DATE` |
| `version` | Record version |
| `creationDate` / `lastModificationDate` | Timestamps (ISO 8601) |

---

## Example Requests

**List all terms:**
```
GET /api/workcap/early-payment-interest-terms/v2/early-payment-interest-terms?offset=0&limit=100
```

**GET list response:**
```json
{
  "metadata": {
    "pageLimit": 100,
    "pageOffset": 0,
    "pageResults": 2,
    "numberOfTotalResults": 2
  },
  "results": [ ... ]
}
```
> Response key is always `results`. Stop paginating when `len(results) < pageLimit`.

**Get a specific term:**
```
GET /api/workcap/early-payment-interest-terms/v2/early-payment-interest-terms/{uuid}
```

---

##  Common Mistakes

| Wrong | Correct |
|---|---|
| Base URL without `/api` prefix | `https://api.demo.kyriba.com/api/workcap/early-payment-interest-terms/v2/...` |
| Field `interestRates[]` | Field `maturityRates[]` |
| `maturityRates[].applyFrom` | `maturityRates[].applicableStartDay` |
| `maturityRates[].applyTo` | `maturityRates[].applicableEndDay` |
| `maturityRates[].rate` | `maturityRates[].markup1` |
| Pagination `page.limit`/`page.offset` | Flat `limit`/`offset` |

---

## Critical Rules

1. This is **read-only** - no create, update, or delete via API
2. Rate brackets are under `maturityRates[]` - not `interestRates[]`
3. Pagination uses flat `offset`/`limit`
4. `404` = Working Capital module not enabled on this environment

---

## Error Reference

| Status | Meaning |
|---|---|
| `200` | Success |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | Term not found or module not enabled |

---

## OpenAPI Spec

- OpenAPI: `https://developer.kyriba.com/static/apis/early-payment-interest/early-payment-interest.yaml`