Skip to main content

Advance a test case to a known lifecycle state.

POST 
/test/cases/:id/advance

Drives a test case to a well-known lifecycle state in a single call.

Purpose: Enables CI pipelines and integrators to exercise the full collection lifecycle — including real webhooks and events — without manual intervention.

Target States:

  • Active — Activates the case from PendingVerification or PendingVerificationInternal. No-op if already Active or Closed.
  • Closed:Paid — Records a payment for amount and closes the case as Paid. Activates the case first if needed. amount is required.
  • Closed:NoPayment — Closes the case with PreLegalExhaustedNoPayment. Activates the case first if needed.

Guards:

  • Returns 400 if the case is not a test case (Classification != Test).
  • Returns 400 if amount is missing when to is Closed:Paid.
  • Returns 400 if to is not one of the valid values.
  • Returns 400 if the case is already closed with a different close code (e.g. already Closed:NoPayment when requesting Closed:Paid).
  • Returns 404 if the case is not found or not owned by the calling creditor.

No-op behaviour: If the case is already at the requested state, the call returns 200 with advanced: false and the current state — no changes are made.

Webhooks: Transitions use the real internal service pipeline. Webhook delivery per target:

  • → Active: fires case.updated to Creditor subscriptions.
  • → Closed:Paid: fires payment.created and case.updated and case.closed to Creditor subscriptions.
  • → Closed:NoPayment: fires case.updated and case.closed to Creditor subscriptions.

All events carry classification: test and are only delivered to webhook subscriptions registered with classification: test.

How to Test:

  1. Create a test case — POST /cases with isTest: true and tag: suite-run-{uuid}. Note the returned id.

  2. Register a test webhook subscription — subscribe to the events you want to assert on (case.updated, payment.created, case.closed) with classification: test and point the URL to your test receiver (e.g. a local ngrok tunnel or a CI webhook sink).

  3. Advance to Active — POST /test/cases/{id}/advance with { "to": "Active" }. Expect { advanced: true, state: "Active" } and a case.updated event on your Creditor subscription.

  4. Advance to Closed:Paid — POST /test/cases/{id}/advance with { "to": "Closed:Paid", "amount": 1000.00 }. Expect { advanced: true, state: "Closed:Paid" } and a payment.created event on your Creditor subscription.

  5. Verify final state — GET /cases/{id} and assert lifecycle: Closed and closeCode: Paid.

  6. Test no-op — Call the same advance again. Expect { advanced: false, state: "Closed:Paid" } and no new webhook events.

  7. Test mismatch error — With the case closed as Paid, call { "to": "Closed:NoPayment" }. Expect 400 with a message describing the conflict.

  8. Assert webhooks — GET /webhooks/events?caseId={id} to verify which events fired.

  9. Reset between runs — DELETE /test/cases?tag=suite-run-{uuid} to clean up all cases created in this run.

Request​

Responses​

Advance result (advanced=true if state changed, advanced=false if already there)