Provision 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. 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.
Control the lifecycle 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. The replay returns the existing relationship and original hosted onboarding URL while its encrypted idempotency record is retained. Later, retrieve the relationship by external_customer_id; create a new Enrollment only when the original URL has expired. Never create a second customer identity after an uncertain response.
Monitor usage and billing state
Call GET /partner-api/v1/usage?period=YYYY-MM for one UTC month. The response reports managed accounts, active Agents and print jobs for operations and the monthly statement; it does not change the fixed invoice amount. If the Partner Program is suspended for non-payment, management and affected printing operations return 403 until service is restored.
Production checklist
- Use an outbound agent connection; do not expose printer ports to the internet.
- Store the stable printer identity instead of relying only on a display name.
- Validate document format, page size and orientation before creating the job.
- Handle terminal status, retry policy and duplicate-print protection explicitly.