Debts, Incidents and Closures

Glossary

Debts

Debts are amounts owed by a client: An amount that the club should have collected but for one reason or another was not collected or has not yet been collected.

A debt, linked to an incident, can prevent a client from booking, passing access control, or even starting a new subscription.

WARNING

It is therefore important to check that a client is not in debt before allowing them to purchase a subscription online, otherwise the sale might not be properly accounted for.

Closures

Accounting closures change a client’s status to "old_client". Their subscriptions, packages, and badges will be deactivated. You will then be able to close their accounting balance, which will then be balanced.

Identifying the debt

GET /:clientToken/financial_summary?contactId=/:clientToken/contacts/:id

This endpoint returns the financial status. With the filter ?contactId=contactIRI you can retrieve the financial status of a given contact. The response includes the number of incidents and the total debt amount.

---

GET /:clientToken/financial?contactId=/:clientToken/contacts/:id

This returns the list of financial sub-entities linked to the contact:

• Payments (to be used)
• Invoices

For invoices, the financialState can be incident if there is a payment incident. You can also check if the financialState is in_progress while the lateDueDate has passed, in which case the invoice is "overdue".

---

GET /:clientToken/invoices/{id}/financial

This endpoint returns the financial status of an invoice. This is especially useful if you want to add a payment on it, which would be refused if it is in incident status. It includes the financialState which may be incident. And the totalIncidentAmount which corresponds to the amount in euros that must be paid for the incident.

Even more important, it also returns its breakdowns (the breakdown of its payments), which themselves can be linked to an ongoing incident ($.breakdowns[i].payment.currentIncident). If one of these incidents is in state open, you can retrieve its amount to pay and keep its id (/{clientToken}/incidents/{id}).

---

GET /:clientToken/incidents?contact=/:clientToken/contacts/:id

This endpoint allows you to retrieve all incidents linked to a contact. Be careful with the state of these incidents. As soon as one of them is in the open state, it means there is an ongoing incident for this client.

Settling the debt via online payment

If the club allows online payment, it is perfectly possible to settle the debt by creating a payableObject with a targetId (or targetIds) related to the incident (as you would for a sale, see dedicated documentation):

POST /clientToken/payable_objects

{
    "contactId": "/:clientToken/contacts/:id",
    "amount": 100, // The incident amount
    "currency": "EUR",
    "clubId": "/:clientToken/clubs/:id",
    "clubCode": "clubCode",
    "checkout": "/:clientToken/checkouts/:id",
    "useWebWallet": false,
    "payableObjects": {
        "incidents": ["/clientToken/incidents/:id"],
    },
    "cancelUrl": "https://www.example.com/cancel",
    "validUrl": "https://www.example.com/valid",
    "useAvailableAmount": false
}

Accounting Closures

A closed member returns to the club or goes to the club’s member area to regularize their situation. It is possible to reopen the client directly from their member profile OR to trigger automated reopening actions from the member area, depending on the club’s policy.

Note, however, that this is often a complex process for which the club usually wants to maintain control over the customer relationship. We therefore strongly recommend to "simply" test if a contact has the status old_client and if so, invite them to contact their club to settle their situation.

A closed contact may have been financially closed while still owing money to the club (being in debt). At the time of reopening, it is perfectly possible (and recommended) to invite the user to settle their past debt.

GET /:clientToken/contact/:id

This endpoint returns the representation of a contact, which includes the property closure. If it is set, it means the client has been closed. The value is the IRI of the closure: /:clientToken/closures/:id

GET /:clientToken/closures/:id

This endpoint allows you to retrieve closure information, including:

Property	Definition
consequenceSummary.addAlert	(true|false) Whether an alert should be displayed
consequenceSummary.contactDebt	The amount of debt, if any
consequenceSummary.lockSale	Whether the closure prevents the client from making purchases
consequenceSummary.subscriptions	The subscriptions impacted by the closure
consequenceSummary.feeAmount	The amount to add to the debt (if any) as handling fees for settling the reopening

Two possibilities:

• If contactDebt is positive: The contact is in debt — see previous sections to settle these debts
• Otherwise, you can proceed directly to the reopening below

Reopen the contact

POST /:clientToken/closures/:id/cancel

This endpoint expects a payload with at least:

{
    "contactSelfUnclosing": true // Pour indiquer que le contact annule de lui-même la clôture
}