> ## Documentation Index
> Fetch the complete documentation index at: https://docs.straddle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Find paykeys that need attention

> Identify expired paykeys, upcoming expirations, and blocked paykeys eligible for unblocking.

Find paykeys with an expiration date that needs attention or a block that may be recoverable. Use the results to identify affected customers and plan the required bank-connection follow-up.

## Before you begin

* Install the [Straddle CLI](/developer-tools/cli/install) and configure an API key with access to the paykeys you want to inspect.
* Confirm your [environment, integration type, and acting account](/developer-tools/cli/auth-context).
* Keep that context and database throughout. For a custom database, add the same `--db PATH` to each `sync` and `expiring` command.

For marketplace integrations, paykeys belong to the platform. These results cover platform-owned paykeys. The selected acting account identifies the local database context used throughout this workflow.

## Run the workflow

<Steps>
  <Step title="Confirm the account and environment">
    ```bash theme={null}
    straddle agent-context --pretty
    ```

    Check `runtime_context.environment`, `runtime_context.integration_type`, and `runtime_context.acting_account`. For SaaS or marketplace, select the account if needed and check again:

    ```bash theme={null}
    straddle use-account ACCOUNT_ID
    straddle agent-context --pretty
    ```
  </Step>

  <Step title="Refresh paykeys">
    ```bash theme={null}
    straddle sync --resources paykeys --full --max-pages 0 --strict --json
    ```

    Confirm a `sync_complete` event and a final `sync_summary` with `success: 1`, `warned: 0`, and `errored: 0`. Review any `sync_warning` or `sync_anomaly` before using the list. Those findings can accompany exit code zero.
  </Step>

  <Step title="Find expiration and block issues">
    ```bash theme={null}
    straddle expiring --days 14 --json
    ```

    The report includes expired paykeys, paykeys with 14 or fewer whole days remaining, and other blocked paykeys marked eligible for unblocking. Change the positive `--days` value to use a different planning window.
  </Step>

  <Step title="Inspect each paykey's current details">
    ```bash theme={null}
    straddle paykeys get PAYKEY_ID --data-source live --no-cache --json
    ```

    Replace `PAYKEY_ID` with an `id` from the report. Check the current status, expiration date when present, customer association, and unblocking eligibility before choosing the follow-up.
  </Step>
</Steps>

## Interpret the results

The result contains `window_days`, `count`, and a `paykeys` array. Each item's `reason` explains why it was included:

| Reason | Meaning |
| - | - |
| `expired` | The recorded expiration date is in the past. |
| `expiring` | The remaining whole days, rounded down, fall within the requested window. |
| `blocked_recoverable` | The paykey has status `blocked` and `unblock_eligible: true`, and was not already included for expiration. |

Items are ordered by those reasons, then by `days_to_expiry`. An expiration reason takes precedence when a paykey also has a recoverable block, so read `status` and `unblock_eligible` alongside `reason`.

`expires_at` applies to certain paykeys. For an item included because of a block, interpret `days_to_expiry` only when it has a valid `expires_at`; a missing date can leave the numeric field at zero. Use the current paykey status to determine usability, including for paykeys outside this report's expiration and block criteria.

## Complete the investigation

Record the paykey ID, customer ID, reason, and follow-up date. For expiration, identify the required bank-connection update for that customer's connection method. For a recoverable block, follow the prerequisites in the [paykey management guide](/guides/bridge/paykeys), including the customer's required bank approval before unblocking. Refresh the records after the update to confirm the result.


## Related topics

- [Payment operations playbooks](/playbooks/overview.md)
- [Troubleshoot Straddle skills](/developer-tools/skills/troubleshooting.md)
- [Check payment progress](/playbooks/payment-progress.md)
- [Investigate failed and returned payments](/playbooks/returns.md)
- [2026 changelog and product updates](/changelog/updates/2026.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.