Licenses & the license_key selector

A License is a single carrier account — one merchant's credentials and configuration for one courier (HFD, Zigzag, Cargo, Self-Pickup, and so on). A merchant account can own several licenses. License-scoped endpoints always act under exactly one license, chosen per request.

Selecting a license

License-scoped requests pick their license with a license_key field whose value is the license's key column:

• On GET endpoints, pass it as a query parameter: ?license_key=...
• On write endpoints (POST/PUT/PATCH/DELETE), pass it as a body field.

Resolution rules

The selector mirrors the base controller's license() logic exactly:

Situation	Outcome
license_key provided and belongs to you, active, not expired	That license is used.
license_key omitted, account has exactly one active license	That license is used (default).
license_key omitted, account has more than one active license	422 validation_failed — license_key is required.
license_key omitted, account has no active license	403 forbidden.
license_key provided but not owned by you (or not found)	403 forbidden.
Selected license is inactive	403 forbidden.
Selected license is expired	403 forbidden.

Exact codes and messages

All errors use the standard error envelope.

Multiple licenses, none specified — 422, code validation_failed:

{
  "error": {
    "code": "validation_failed",
    "message": "You have multiple licenses — specify which one with license_key.",
    "status": 422,
    "details": {
      "license_key": [
        "The license_key field is required when the account has more than one license."
      ]
    }
  }
}

No active license — 403, code forbidden, message Your account has no active license.

license_key not owned / not found — 403, code forbidden, message The requested license does not belong to you.

License inactive — 403, code forbidden, message This license is inactive.

License expired — 403, code forbidden, message This license has expired.

Discovering your licenses

Call GET /account — the response embeds every license the account owns (each with its key, is_active, is_expired, carrier company, and settings). Use a license's key value as the license_key selector.