# Contribution Catalogue

The Contribution Catalogue lets you inspect the structure and rates of social contributions **without triggering a payroll calculation**. This is useful for building UI previews, validating rate configurations, or understanding the regulation schema.

## Overview

The catalogue exposes two complementary resources:

| Resource | Endpoint | What it returns |
|----------|----------|-----------------|
| **Wage Type Definitions** | `GET /payrolls/{payrollId}/wagetypes` | Contribution structure with static attributes |
| **Lookup Tables** | `GET /regulations/{regulationId}/lookups` | Rate tables (e.g., URSSAF, Retraite, CSG-CRDS) |
| **Lookup Entries** | `GET /regulations/{regulationId}/lookups/{lookupId}/values` | Individual rate key-value pairs |

## Step 1: Read the Contribution Catalogue

Retrieve all wage type definitions for a payroll. Each definition includes static **attributes** that describe its role in the payroll calculation.

```bash
GET /partners/{partnerId}/tenants/{tenantId}/payrolls/{payrollId}/wagetypes
```

### Example Response

```json
[
  {
    "id": 42,
    "wageTypeNumber": 210,
    "name": "Maladie salariale",
    "attributes": {
      "part": "salariale",
      "categorie": "cotisation",
      "lookupName": "TauxURSSAF",
      "lookupKey": "maladie_salarial",
      "plafondRef": "none"
    }
  },
  {
    "id": 55,
    "wageTypeNumber": 300,
    "name": "Vieillesse plafonnée salariale",
    "attributes": {
      "part": "salariale",
      "categorie": "cotisation",
      "lookupName": "TauxURSSAF",
      "lookupKey": "vieillesse_plafonnee_salarial",
      "plafondRef": "PlafondSS"
    }
  },
  {
    "id": 71,
    "wageTypeNumber": 402,
    "name": "AGIRC-ARRCO T1 salariale",
    "attributes": {
      "part": "salariale",
      "categorie": "cotisation",
      "lookupName": "TauxRetraite",
      "lookupKey": "agirc_arrco_t1_salarial",
      "plafondRef": "PlafondSS"
    }
  }
]
```

### Attribute Schema

| Attribute | Description | Example values |
|-----------|-------------|----------------|
| `part` | Employee or employer share | `salariale`, `patronale` |
| `categorie` | Contribution category | `cotisation`, `base`, `plafond`, `net` |
| `lookupName` | Rate table name | `TauxURSSAF`, `TauxRetraite`, `TauxCSGCRDS` |
| `lookupKey` | Key within the rate table | `maladie_salarial`, `vieillesse_plafonnee_salarial` |
| `plafondRef` | Ceiling reference | `PlafondSS`, `none` |

## Step 2: Resolve Rate Values

Use the lookup endpoints to retrieve the actual rate values referenced by wage type attributes.

### List Available Lookup Tables

```bash
GET /partners/{partnerId}/tenants/{tenantId}/regulations/{regulationId}/lookups
```

```json
[
  { "id": 1, "name": "TauxURSSAF", "description": "URSSAF contribution rates" },
  { "id": 2, "name": "TauxRetraite", "description": "Complementary pension rates" },
  { "id": 3, "name": "TauxCSGCRDS", "description": "CSG and CRDS rates" }
]
```

### Get Entries for a Specific Table

```bash
GET /partners/{partnerId}/tenants/{tenantId}/regulations/{regulationId}/lookups/1/values
```

```json
[
  { "key": "maladie_salarial", "value": "0" },
  { "key": "maladie_patronal", "value": "0.07" },
  { "key": "vieillesse_plafonnee_salarial", "value": "0.069" },
  { "key": "vieillesse_plafonnee_patronal", "value": "0.0855" },
  { "key": "vieillesse_deplafonnee_salarial", "value": "0.004" },
  { "key": "vieillesse_deplafonnee_patronal", "value": "0.0202" }
]
```

### Resolving a Rate

To find the rate for **WT 300 — Vieillesse plafonnée salariale**:

1. Read its attributes: `lookupName: "TauxURSSAF"`, `lookupKey: "vieillesse_plafonnee_salarial"`
2. Find the lookup table named `TauxURSSAF` (id: 1)
3. Query its values and find key `vieillesse_plafonnee_salarial` → `"0.069"` (6.9%)

## Catalogue vs Simulation

| Aspect | Catalogue | Simulation (Payrun) |
|--------|-----------|---------------------|
| **Purpose** | Browse structure and reference rates | Calculate actual amounts |
| **Triggers calculation** | No | Yes |
| **Returns amounts** | No (rates only) | Yes (computed values) |
| **Use case** | UI scaffolding, rate preview, configuration audit | Pay slip generation, what-if scenarios |
| **Performance** | Instant (no computation) | Depends on employee count |

Use the **catalogue** to build contribution overviews and validate rate configurations. Use **simulations** (via [payrun jobs](/api#Payrun-jobs)) when you need actual computed amounts for specific employees.

## Next Steps

- [Quickstart](/quickstart) — Run your first payroll simulation
- [Case Fields Reference](/reference/case-fields) — Employee input variables
- [API Reference](/api) — Full endpoint documentation