Using the software vendor’s cost sponsorship — or deliberately not

A workshop uses the tapinomahub functions through its workshop software. The software vendor has offered to cover the vehicle queries. But the workshop also has its own balance and its own terms — and does not want to find out only from the invoice who paid for which request.

In the Hub, sponsorship is an explicit relationship with two sides: the sponsor grants it and can release the choice of terms, the beneficiary sees it and decides. None of this happens silently — on partner terms not even when a request falls outside the sponsorship.

What this case requires

• A granted sponsorship. It originates with the sponsor; the beneficiary cannot create it.
• Release of partner terms if these are to be chosen. Without partnerTermsAllowed, choosing partner answers with 403.
• A look at the covered endpoints. endpointKeys says what the sponsorship applies to — not every request is included.
• A decision for requests outside the sponsorship. Under partner an uncovered request is rejected, not paid from your own balance.

The sequence

The table names the responsible call per stage and what exists afterwards. The reasoning for why a stage cannot be skipped follows below it.

Why each stage is needed

1. Review the sponsorships. GET /client/sponsorship-grants/received lists per sponsorship reference, sponsor, endpointKeys, startsAt, endsAt, active, partnerTermsAllowed and partnerTermsChosen. This shows what is covered and whether the choice is open at all.
2. Choose the terms. PUT /client/sponsorship-grants/received/{grantReference}/billing-mode takes mode with own or partner. Under partner your own balance stays untouched; without the sponsor’s release the call answers with 403. If the sponsor withdraws the release, the choice falls with it.
3. Read the balance. GET /client/credits returns balanceCents, creditLimitCents and availableCents. When the business works on partner terms, billingMode is partner and the amounts are null — its balance is not charged and therefore not reported.
4. Read the usage. GET /client/usage names the period, per plan used, includedMonthlyQuantity and remaining, and per endpoint used and chargedCents. This lets you check whether the requests went where the choice was meant to send them.

curl -X PUT \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"mode":"partner"}' \
  'https://api.tapinomahub.com/client/sponsorship-grants/received/<grantReference>/billing-mode'

What you end up with

In the end the business knows for every request who pays: on partner terms, the sponsor for the covered endpoints; on its own terms, billing draws first on the business’s own plan and balance, and the sponsor steps in only as a fallback. And on partner terms a request outside the sponsorship is visibly rejected instead of quietly costing balance.

Where to find this in the documentation

The binding field lists, error codes and sample responses live in this surface’s OpenAPI contract at docs.tapinomahub.com (tapinoma-hub). All use cases arranged by surface and role: overview of the use cases.