Skip to main content

Agreement events (agreement.*)

Facts from the lifecycle of negotiation agreements. In entity events, data is the agreement with the summarized customer (person) and, once generated, the installments (installments).

status values: proposed · accepted · active · completed · cancelled · defaulted. Installment status values: pending · paid · overdue · cancelled.

agreement.created​

Fires when an agreement proposal is created (status: "proposed"). The installments do not exist yet — they are generated on acceptance.

{
  "event": "agreement.created",
  "timestamp": "2026-07-23T12:00:00.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "id": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c",
    "publicId": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
    "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
    "workspaceId": null,
    "companyId": null,
    "businessUnitId": null,
    "personId": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
    "negotiationOfferId": null,
    "originalTotal": "4820.00",
    "discountAmount": "820.00",
    "finalTotal": "4000.00",
    "numberOfInstallments": 4,
    "installmentValue": "1000.00",
    "firstDueDate": "2026-08-05T00:00:00.000Z",
    "status": "proposed",
    "acceptedAt": null,
    "acceptedIp": null,
    "termsAccepted": null,
    "cancelledAt": null,
    "cancellationReason": null,
    "completedAt": null,
    "externalId": null,
    "customData": null,
    "tags": [],
    "metadata": {},
    "createdAt": "2026-07-23T12:00:00.000Z",
    "updatedAt": "2026-07-23T12:00:00.000Z",
    "deletedAt": null,
    "person": {
      "id": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
      "name": "Padaria Pão Quente Ltda",
      "documentNumber": "12345678000190",
      "documentType": "cnpj"
    }
  }
}

agreement.updated​

Fires when the agreement is changed. Same shape as agreement.created, plus the installments array:

{
  "installments": [
    {
      "id": "1a3c5e7f-9b2d-4e6f-8a0c-3d5f7b9e1a2c",
      "publicId": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f80",
      "agreementId": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c",
      "installmentNumber": 1,
      "dueDate": "2026-08-05T00:00:00.000Z",
      "amount": "1000.00",
      "paidAmount": null,
      "paidAt": null,
      "status": "pending",
      "deletedAt": null,
      "customMetadata": null,
      "metadata": {},
      "externalId": null,
      "createdAt": "2026-07-23T15:20:00.000Z",
      "updatedAt": "2026-07-23T15:20:00.000Z"
    }
  ]
}

agreement.accepted​

Fires when the agreement is accepted — the installments are generated and the collection rule of the covered charges is halted before the event. The shape of data depends on who accepted:

Accepted by the operator (API/dashboard) — full agreement (same shape as agreement.updated, with installments), now with status: "accepted" and acceptedAt, acceptedIp and termsAccepted filled in.

Accepted by the debtor (portal) — lean summary, with numeric values:

{
  "event": "agreement.accepted",
  "timestamp": "2026-07-23T18:45:12.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "id": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c",
    "originalTotal": 4820.0,
    "discountAmount": 820.0,
    "finalTotal": 4000.0,
    "numberOfInstallments": 4,
    "installmentValue": 1000.0,
    "firstDueDate": "2026-08-05T00:00:00.000Z",
    "status": "accepted",
    "acceptedAt": "2026-07-23T18:45:11.000Z",
    "personId": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60"
  }
}

Handle both shapes: distinguish by the set of fields, or fetch GET /api/v1/agreements/{id} for the canonical state.

agreement.cancelled​

Fires on cancellation. data is the full agreement (with installments), with status: "cancelled" and cancelledAt and cancellationReason filled in; pending/overdue installments move to cancelled.

agreement.broken​

:::caution Planned — not emitted yet This event is reserved in the catalog but is not emitted yet: because an agreement break is marked manually (there is no automatic detection), nothing in the system fires agreement.broken today. To track defaulted agreements, query the defaulted status via GET /api/v1/agreements, or monitor the agreement events that are already emitted (agreement.accepted, agreement.cancelled). :::

Once emitted, it will fire when the agreement is broken (an unpaid installment takes the agreement to defaulted), with data in the family's entity shape (full agreement with installments).

agreement.completed​

Fires when all installments are settled (status: "completed", completedAt filled in). data follows the family's entity shape.

agreement.deleted​

Fires on (logical) deletion; completed agreements cannot be deleted.

{
  "event": "agreement.deleted",
  "timestamp": "2026-07-23T12:00:00.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": { "id": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c" }
}