Refund API

The Refund Calculators API lets external systems request VSC and Gap refund calculations. Your system sends contract data; the API returns calculated refund totals in the same response.

This documentation covers integrator-facing endpoints only. Admin setup, internal configuration, and contract-pull integrations require a signed-in account.

Server-to-server integrations use an API key issued by your administrator.

Send the key on every request using one of these headers:

Authorization: Bearer rfnd_<your-api-key>

Or:

X-API-Key: rfnd_<your-api-key>

API keys are tied to a service account. Contact your administrator to request a key. Keys are shown once at creation and cannot be retrieved later.

VSC (Freedom): POST /api/calculate/freedom

Gap: POST /api/calculate/gap

Both endpoints require Content-Type: application/json.

Required for API key requests: contractNumber plus the calculator fields in the tables below.

Each API-key calculate request is automatically saved as a tracked record.

Response fields: contractNumber, results, warnings, recommendation (VSC only), case.

*Ignored when unlimitedMileage is true.

Yes — the VSC client refund amount is in the calculate response.

Field name: clientRefundToCustomer

Meaning: amount the dealer/client refunds to the customer (markup side).

VSC returns two paths. Read recommendation.recommended first, then pick the matching path:

Other amounts on the same object:

- amountSentToClient — what Freedom sends the dealer

- totalCustomerReceives — client refund + amount sent to client (customer-facing total)

- agentChargeback — prorated agent commission chargeback

Unlimited mileage products: use the days path only (results.refundPerDays).

Gap client refund amount: results.refund.clientRefundToCustomer

Customer-facing total: results.refund.totalCustomerReceives

Amount sent to dealer: results.refund.amountSentToClient

Replace YOUR_API_KEY and field values with your contract data.

curl -s -X POST "https://www.fwrefund.com/api/calculate/freedom" \

-H "Authorization: Bearer YOUR_API_KEY" \

-H "Content-Type: application/json" \

-d '{"contractNumber":"FW-12345","startMileage":101520,"endMileage":204145,"contractTermMiles":5000,"contractTermDays":1095,"startDate":"2024-06-25","endDate":"2025-10-29","cost":1928,"markup":1050,"deductible":50,"approvedClaimAmount":0}'

Use your deployment URL as BASE_URL (for example, the URL shown after you sign in).

Errors return JSON: { "error": "message", "hint": "how to fix it" }

Invalid JSON body

This means the HTTP body failed to parse as JSON. It is not a field-validation error.

Fix:

- Send header Content-Type: application/json

- Use raw JSON (Postman/Insomnia: Body → raw → JSON), not form fields

- Use double quotes on keys and strings; no trailing commas

- Do not send an empty body

- Include contractNumber on API-key calculate calls