Create and manage customer accounts
Provision one isolated CloudPrint Account for each customer and keep your external customer identifier mapped to the stable Partner Account Relationship and App Installation returned by CloudPrint.
Authenticate the Partner API
Create a new single-use RS256 application assertion for every Partner API call. Its iss and sub identify the Developer Application, kid selects an active public key and aud must equal the configured Partner Management audience. Send it as a Bearer credential to /partner-api/v1/*; do not reuse an Installation Access Token for management calls.
Provision idempotently
Before calling POST /partner-api/v1/accounts, persist the complete pending operation: Idempotency-Key, state, name, permissions and callback. After a timeout, repeat the exact body and key with only a fresh application assertion; do not create a second customer, state or key.
Store the stable bindings
Persist external_customer_id, relationship_id, installation_id, relationship state and timestamps in one integration record. CloudPrint resolves and de-duplicates external_customer_id within the authenticated Developer Application, so separate staging and production Applications may safely use the same customer identifier. Use relationship_id for Partner lifecycle calls and installation_id to issue Print API tokens. Keep cloudprint_account_id only if you want to verify it against account_id in the token response.
Retrieve one customer directly
Use GET /partner-api/v1/accounts/{relationshipId} when you have the relationship. For deterministic reconciliation by your tenant ID, call GET /partner-api/v1/accounts?external_customer_id={tenantId}. The unfiltered GET /partner-api/v1/accounts uses limit, opaque cursor and next_cursor; exact external-ID lookup cannot be combined with a cursor. Health excludes revoked Agents and their printers. An Agent is online only with status online and a heartbeat in the last minute; an online printer also requires its owning Agent to meet that condition. Agent onboarding reaches onboarding_status=ready after the first authenticated heartbeat even if no printers are reported. Enable printing only when status=active, online_agent_count > 0 and online_printer_count > 0.
Change account status explicitly
Use POST /partner-api/v1/accounts/{relationshipId}/{action} with suspend, resume or close. Suspension revokes issued Installation tokens; resume requires a fresh token. Close is terminal. A suspended managed account blocks affected Print API operations with 403 remote_printing.account.service_suspended.
Recover a lost provisioning response
Repeat POST /partner-api/v1/accounts with the original body, original Idempotency-Key and a fresh application assertion. While the encrypted idempotency record is retained, the replay returns the existing relationship and the original onboarding URL. Later, retrieve the relationship by external_customer_id; create a new Enrollment only after the original link has expired. Never create a second customer identity after an uncertain response.
Monitor usage and billing
Call GET /partner-api/v1/usage?period=YYYY-MM for one UTC month. The response reports managed accounts, active Agents and print jobs for operational reporting and the monthly statement; it does not change the agreed invoice amount. If Developer Account production access is suspended, management and affected printing operations return 403 until access is restored.