Limitations

Before a business can send payments or add accounts, it must meet Melio’s risk and compliance requirements. Limitations tell you, per operation, whether a business is allowed to perform that operation today and, if not, why. Use the limitations endpoint to check eligibility up front, so you can guide a business through what it still needs to do instead of letting a write request fail with a 403.

GET /limitations

Authentication: API key (Authorization: Bearer <api-key>). Required header: Melio-Entity-Id - the business to check, either an entity id (ent_<uuid>) or me for the partner’s sole entity.

Response

The response is a list of capabilities, one per limitable operation.

{
  "capabilities": [
    {
      "operation": "payment.domestic:write",
      "allowed": false,
      "reasons": [
        {
          "code": "MissingInformation",
          "message": "Additional information is required before this business can send payments.",
          "missingFields": ["taxInfo"]
        }
      ]
    },
    {
      "operation": "account.internal:write",
      "allowed": true,
      "reasons": []
    },
    {
      "operation": "account.external:write",
      "allowed": true,
      "reasons": []
    }
  ]
}

Field	Description
`operation`	The operation this entry gates, named `resource.subtype:action`.
`allowed`	Whether the business may perform this operation today.
`reasons`	Why the operation is blocked. Empty when `allowed` is `true`.

Only write operations (create, update, delete) can be limited. Read operations are always allowed and never appear in the list. New operations are added to this list over time, so treat unknown operation values leniently rather than rejecting them.

Operations

`operation`	Gates
`payment.domestic:write`	Creating, editing, or canceling domestic payments.
`account.internal:write`	Adding or modifying internal (pay-from) accounts.
`account.external:write`	Adding or modifying external (payee) accounts.

Reasons

When allowed is false, each entry in reasons explains one blocker.

Field	Description
`code`	Machine-readable reason code (see below). Branch on this.
`message`	Static, English message approved for external display. Safe to show a business as-is.
`missingFields`	Dot-paths into the entity that must be completed to lift this reason, for example `taxInfo`. Empty when the reason is not about missing information.
`contactEmail`	A Melio contact address for resolving the reason. Present only when one is available.

Common code values:

`code`	Meaning
`MissingInformation`	The entity is missing required details. See `missingFields` for what to collect.
`AccountBlocked`	The business is blocked from this operation.
`AccountUnderReview`	The business is under review; try again once review completes.
`OutstandingBalance`	An outstanding balance must be resolved first.
`LocationRestricted`	The operation is restricted for the business’s location.
`AccountUnresponsive`	Melio needs a response from the business to proceed.

Treat code as an open set and handle unknown values gracefully. Always fall back to displaying message, which is written for a business to read.

Resolving a `MissingInformation` reason

When the reason is MissingInformation, missingFields lists dot-paths into the entity that need to be completed. Collect and submit those fields (for example, by updating the entity), then re-check limitations.

{
  "code": "MissingInformation",
  "message": "Additional information is required before this business can send payments.",
  "missingFields": ["taxInfo"]
}

Limitations and write errors

Limitations are the same restrictions that surface as errors when you attempt a blocked write. If a business is not eligible, the corresponding write endpoint returns:

Status	`code`	Meaning
`403 Forbidden`	`BUSINESS_NOT_ELIGIBLE`	The business is restricted from this operation. Check `GET /limitations` for the reasons.

Checking limitations first lets you avoid the 403 and tell the business exactly what to fix. See Errors for the response shape.

Staying up to date

Limitations change as a business’s risk and compliance status changes. Subscribe to the api.limitation.updated webhook event and re-fetch GET /limitations when it fires, rather than polling.

Get started

Core resources

Building with the API

Risk, compliance & going live

Tools

Response

Operations

Reasons

Resolving a `MissingInformation` reason

Limitations and write errors

Staying up to date

​Response

​Operations

​Reasons

​Resolving a MissingInformation reason

​Limitations and write errors

​Staying up to date

Response

Operations

Reasons

Resolving a `MissingInformation` reason

Limitations and write errors

Staying up to date