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",
  "organization_id": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "workspace_id": "5e8d1c4b-7a2f-4c9e-b3d6-0a1f2e3d4c5b",
  "data": {
    "id": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c",
    "public_id": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
    "organization_id": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
    "workspace_id": "5e8d1c4b-7a2f-4c9e-b3d6-0a1f2e3d4c5b",
    "company_id": null,
    "business_unit_id": null,
    "person_id": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
    "negotiation_offer_id": null,
    "original_total": 4820.00,
    "discount_amount": 820.00,
    "final_total": 4000.00,
    "number_of_installments": 4,
    "installment_value": 1000.00,
    "first_due_date": "2026-08-05T00:00:00.000Z",
    "status": "proposed",
    "accepted_at": null,
    "accepted_ip": null,
    "terms_accepted": null,
    "cancelled_at": null,
    "cancellation_reason": null,
    "completed_at": null,
    "external_id": null,
    "custom_data": null,
    "tags": [],
    "metadata": {},
    "custom_metadata": null,
    "created_at": "2026-07-23T12:00:00.000Z",
    "updated_at": "2026-07-23T12:00:00.000Z",
    "deleted_at": null,
    "person": {
      "id": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
      "name": "Padaria Pão Quente Ltda",
      "document_number": "12345678000190",
      "document_type": "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",
      "public_id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f80",
      "agreement_id": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c",
      "installment_number": 1,
      "due_date": "2026-08-05T00:00:00.000Z",
      "amount": 1000.00,
      "paid_amount": null,
      "paid_at": null,
      "status": "pending",
      "deleted_at": null,
      "custom_metadata": null,
      "metadata": {},
      "external_id": null,
      "created_at": "2026-07-23T15:20:00.000Z",
      "updated_at": "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",
  "organization_id": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "workspace_id": "5e8d1c4b-7a2f-4c9e-b3d6-0a1f2e3d4c5b",
  "data": {
    "id": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c",
    "original_total": 4820.0,
    "discount_amount": 820.0,
    "final_total": 4000.0,
    "number_of_installments": 4,
    "installment_value": 1000.0,
    "first_due_date": "2026-08-05T00:00:00.000Z",
    "status": "accepted",
    "accepted_at": "2026-07-23T18:45:11.000Z",
    "person_id": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60"
  }
}

Handle both shapes: distinguish by the set of fields, or fetch GET /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 /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",
  "organization_id": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "workspace_id": "5e8d1c4b-7a2f-4c9e-b3d6-0a1f2e3d4c5b",
  "data": { "id": "6e4f2a8c-3b5d-4c7e-9f1a-4b6d8e0f2a4c" }
}