clientspace/post_credits_by_id

Tool: create

Allocate sending credits from the parent agency to a clientspace. Only the parent agency may call this, and only against a clientspace with separate credits — a shared-credit clientspace is rejected (switch it to separate credits via clientspace/patch_by_id first). Credits are credited to the clientspace first, then debited from the agency; a failed agency debit is reversed on the clientspace.

This moves credits one way only. There is no de-allocation operation, and amount must be a positive integer — 0 or a negative value is rejected with 422 Amount must be a positive integer, so credits cannot be pulled back out of a clientspace through the API. Allocate what is needed rather than a large round number.

externalReference makes the call idempotent, and a stuck pending replay needs a balance check before you retry. Set externalReference on every automated call. A replay of the same reference returns 200 with the original allocation instead of moving credits again; reusing it with a different clientspace or amount is rejected with 422 (one reference identifies exactly one allocation). A blank/whitespace value counts as omitted. A replayed failed allocation is returned as-is and never re-run — retry with a new reference once the cause is fixed. But a replayed pending allocation older than 15 minutes is returned as failed because the original request crashed before finishing — and it may have crashed after the credits already moved, so check the balance with clientspace/get_credits_by_id before retrying with a new reference, or you risk a double allocation.

Arguments

name	type	req	notes
id	integer	✓	Clientspace ID — the object's `clientspaceId`

Body

field	type	req	constraints	description
amount	integer	✓	≥1	Sending credits to move from the agency to the clientspace
note	string	–	≤256 chars	Free-text note for the allocation; defaults to `Added from main account` when omitted
externalReference	string	–	≤128 chars	Idempotency key, unique per agency — see the caveat above

Response

201 — Credits allocated; new allocation object (fields below). 200 — Idempotent replay: externalReference was already used; returns the original allocation unchanged, no credits moved.

field	type	description
allocationId	integer	Unique identifier of the allocation.
clientspaceId	integer	Clientspace the credits were allocated to.
amount	integer	Credits moved from the agency to the clientspace.
note	string	The note recorded with the allocation.
externalReference	string	The idempotency key it was created with; null when none was given.
status	string	`pending` while in flight, `completed` once both ledger legs succeeded, `failed` if the move could not complete.
balance	integer	Clientspace's sending-credit balance, read after the allocation.
agencyBalance	integer	Parent agency's sending-credit balance, read after the allocation.
createdAt	string	When the allocation was created.

Errors: 400, 401, 402 (INSUFFICIENT_SENDING_CREDITS — insufficient credits on the agency), 403, 404, 406, 409, 415, 422, 429, 500 — shared schema: schemas/errors.

Invoke

Call create with name: "clientspace/post_credits_by_id".