Transfer limits

Read a sender's transfer caps and what is left to send, and know when a transfer will pause.

If your business has a limits policy, each sender has caps in USD: per transfer, daily, weekly, monthly and annual. Gravv does not refuse a transfer over a cap. It returns the transfer as paused, and you handle it as described in Paused transfers. Read the caps before a large payout to know whether it will pause.

Example. Maria has a weekly cap of 2,500.00 USD and has sent 2,200.00 USD this week, so 300.00 USD is left. You send 1,500.00 USD. The transfer pauses with breached_window weekly and remaining_usd 300.00. If requirements offers it, you can resume it with stronger sender verification. You can also send 300.00 USD instead, or let it expire. If it expires, Gravv refunds the fee.

Read a customer's limits

Send GET /v1/customers/{customer_id}/limits.

curl --request GET \
     --url https://api.gravv.xyz/v1/customers/7c9e6679-7425-40de-944b-e07fc1f90ae7/limits \
     --header 'Api-Key: <API_KEY>'

{
  "data": {
    "subject_type": "customer",
    "subject_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "tier_code": "basic",
    "tier_assignment": "kyc",
    "caps_basis": "tier",
    "mode": "enforce",
    "blocked": false,
    "usage_available": true,
    "as_of": "2026-10-13T09:15:22Z",
    "windows": {
      "per_transfer": { "cap_usd": "2000.00", "used_usd": null, "remaining_usd": null },
      "daily": { "cap_usd": null, "used_usd": "0.00", "remaining_usd": null },
      "weekly": { "cap_usd": "2500.00", "used_usd": "2200.00", "remaining_usd": "300.00" },
      "monthly": { "cap_usd": "10000.00", "used_usd": "6400.00", "remaining_usd": "3600.00" },
      "annual": { "cap_usd": "100000.00", "used_usd": "18000.00", "remaining_usd": "82000.00", "requires_approval": false }
    },
    "next_tier": null,
    "candidate_tiers": null
  },
  "error": null
}

How to read the response:

The smallest remaining_usd is the most this sender can send now (here 300.00, weekly).
cap_usd null means that window has no cap.
Amounts are USD. Gravv converts a transfer in another currency to USD first, and some policies count the fee too.
Weeks are ISO weeks, Monday to Sunday, in UTC.
mode says what the policy does: off (no limits), shadow (Gravv measures usage but nothing pauses) or enforce (transfers over a cap pause).
blocked: true means the sender cannot send at all. Their transfers return 422 ERROR_CODE_SUBJECT_BLOCKED.
next_tier shows the caps the sender would get at the next verification level, when there is one.

A 404 not found: no limits policy applies means your business has no limits policy, not "unlimited by tier". A 404 not found: subject means the customer is not one of yours.

Read a remitter's limits

If you send on behalf of end senders and identify them with remitter_verification.remitter_id, Gravv counts their usage per remitter. Read it with GET /v1/limits/remitters/{remitter_id}. The response has the same shape, with subject_type remitter.

curl --request GET \
     --url https://api.gravv.xyz/v1/limits/remitters/rem-maria-lopez-01 \
     --header 'Api-Key: <API_KEY>'

When a transfer is over a cap

The API returns the transfer as paused, with pause_reason set to the window (per_transfer, daily, weekly, monthly, annual or annual_requires_approval), plus breached_window, remaining_usd, requirements and expires_at. You can:

Resume it with what requirements asks for, such as a remitter_verification at a higher level.
Contact support if the requirement is admin_review. Only Gravv can release it.
Let it expire. Send at most remaining_usd now and the rest later.

Response	Why	Fix
422 `transfers are not permitted for this sender` (`ERROR_CODE_SUBJECT_BLOCKED`)	The sender is blocked	Contact support. Do not retry
503 `transfer limits are temporarily unavailable, please retry` (`ERROR_CODE_LIMITS_UNAVAILABLE`)	Gravv cannot check limits right now	Retry with backoff
409 `client_reference has already been used for a different transfer …` (`ERROR_CODE_DUPLICATE_TRANSACTION`)	Under an enforced policy, you reused a `client_reference` with a different body	Use a new `client_reference` for each payout
409 `a transfer with this client_reference is still being processed; retry shortly` (`ERROR_CODE_TRANSFER_IN_PROGRESS`, `Retry-After: 1`)	You retried while the first request was still running	Wait a second and retry
400 `subject_id "x" is not a customer id`	The id is not a UUID	Send the customer id

Testing in sandbox

In sandbox, a new customer's policy is in shadow mode, so nothing pauses for a limit. used_usd stays 0.00, because sandbox transfers do not count toward usage. Ask support to set a test policy if you need to test a limit pause.