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 (api-key: <api-key>, no Bearer prefix). 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": "payment.international:write",
      "allowed": false,
      "reasons": [
        {
          "code": "MissingInformation",
          "message": "Additional information is required before this business can send international payments.",
          "missingFields": ["website", "beneficialOwners"]
        }
      ]
    },
    {
      "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.
`payment.international:write`	Creating, editing, or canceling international payments (the `international-fx` and `international-gusd` rails).
`account.internal:write`	Adding or modifying internal (pay-from) accounts.
`account.external:write`	Adding or modifying external (payee) accounts.

payment.domestic:write and payment.international:write are decided independently. Which one applies to a given payment is determined by the receiving account’s rail, so a business may be able to pay domestically while being blocked internationally, or the reverse. Check the one matching the payment you intend to create.

payment.international:write also reports onboarding data that is still outstanding, not only risk restrictions - so it can be blocked purely because the business has not finished international onboarding yet. See International onboarding for what that involves.

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 wire model that must be completed to lift this reason, for example `taxInfo` or `owner.dateOfBirth`. Empty when the reason is not about missing information.
`contactEmail`	A Melio contact address for resolving the reason. Present only when one is available.

Current code values:

`code`	Meaning
`MissingInformation`	The entity is missing required details. See `missingFields` for what to collect.
`EntityBlocked`	The business is blocked from this operation.
`EntityUnderReview`	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.
`EntityUnresponsive`	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", "owner.dateOfBirth"]
}

A path with a dot addresses a nested field - owner.dateOfBirth is dateOfBirth on the entity’s owner. For payment.international:write, missingFields may also name beneficialOwners, which is submitted through its own endpoint rather than as an entity field.

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.

The error message names the operation that was refused, for example Business is not eligible to make international payments. See the limitations endpoint for details. It does not carry the reason codes - fetch GET /limitations for those. 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