Skip to main content

​
Outcome

Releasing a company ends your partner connection and revokes all your access to its company data, memberships, cases, and updates. The client retains their users, submitted cases, company-created drafts, portal access, and company credentials.

​
When to release

Release a company when the engagement ends on your side — the client cancelled your product, moved to a different provider, or the company was connected by mistake. Release also ends provisional access before the client has confirmed the connection. Releasing is not deleting. There is no company delete in the Partner API; a released company remains readable through its own credentials and through paywise, and it stays attributed to you in paywise’s records. Two things do change on release:
  • Orders you created on the company’s behalf and never submitted are deleted, and your pending case commands are invalidated. Submitted orders, their cases, and drafts the company created itself are untouched.
  • The company’s external_reference is cleared. You may onboard a new company under the same reference afterwards; the released company is no longer found by it.

​
Prerequisites

  • A Partner key.
  • The company UUID you stored at onboarding (never the customer_number).
  • A verified Partner webhook receiver or a feed consumer, because the release emits company.access.revoked and your access gate must observe it.

​
1. Release with an idempotent command

reason is optional and up to 5000 characters. It is validated and then discarded: paywise does not store it, and it is never included in the webhook payload or in any company read. On a timeout, replay the same key and body: the replay returns the committed result with Idempotency-Replayed: true and does not emit a second event.

​
Representative response

The response is a release receipt: the released company’s id and its case_access, which is always unavailable. The company is omitted from your company list, and company, membership, and Case Management API requests return 404 after disconnection. Membership administration closes with the release: add, role change, resend, cancel, and revoke all answer the same 404 as the reads, so finish any pending invitation work before you release.

​
2. Handle the access event

The release emits one company.access.revoked whose data carries reason: "partner_released", so your access handler can distinguish your own release from a client decline. The event goes to every Partner subscription that includes it and to the event feed. Run the same reconciliation you use for every access event — see Handle access changes — and apply the unavailable branch: gate delegated writes, keep finalized-case knowledge, discard draft work you created on the company’s behalf.

​
3. Verify

  • GET /partner/v2/companies/{id}/ and its membership routes return 404.
  • The company is absent from GET /partner/v2/companies/.
  • Any /v2/ request carrying X-On-Behalf-Of-Company for that company answers 404, as for every company you do not have access to.
  • Retrying with the original idempotency key returns the same release receipt. A new release command after disconnection returns 404.

​
Failure and recovery

  • 404: the company is not one of yours, or its UUID is wrong. Do not fall back to matching by name or external_reference — read your stored UUID. A released company has no external_reference any more.
  • 404 after an ambiguous release: keep access blocked. Retry with the original idempotency key to recover the receipt; do not create a new company.
  • A client admin can reconnect the same company through the client-authorized connection flow. Deleted drafts remain deleted and missed events are not replayed. Fetch current state before resuming future work.