Feature flags

Configure account-level feature-flag preferences that control supported capabilities for your account.

Prerequisites

1. Store an API key that can access the account.
2. Identify the account ID you want to configure.

How feature flags apply

Feature flags are stored on the account as featureFlags. Set them by updating the account with POST /v1/accounts/{accountId}, one account at a time.

Due can also apply a flag at the platform level. When Due flags a platform, all accounts on that platform inherit the flag automatically. Contact Due to request a platform-level change; you cannot set it through the account endpoint.

A platform-wide provider change can affect existing accounts because they may need to complete an endorsement before they can use the provider.

Available flags and values

Each flag takes one of four values, which control how strongly routing favours or avoids the flagged provider:

Only two feature flags are currently live: erebor and swift-named.

Check a channel's feature-flag requirements

Before setting an account preference, retrieve the available channels and inspect each channel's featureFlags and endorsementsRequired fields. A channel's featureFlags array lists the flag that applies to that provider, while endorsementsRequired lists endorsements the account must complete to use it.

curl --request GET \
  --url 'https://api.due.network/v1/channels?onlyAvailable=true' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Due-Account-Id: <ACCOUNT_ID>' \
  --header 'accept: application/json'

For example, a USD wire channel can identify the Erebor provider with erebor and require the usd_bank_erebor_v1 endorsement:

{
  "rail": "wire",
  "type": "static_deposit",
  "currencyCode": "USD",
  "feeBps": 25,
  "limitMax": "5000000",
  "endorsementsRequired": ["usd_bank_erebor_v1"],
  "featureFlags": ["erebor"]
}

Set a preference only for a flag returned by the channel you intend to use. A prefer or require value does not bypass the channel's residency, permission, or endorsement requirements.

1. Retrieve the account preferences

The account's current preferences are returned in the featureFlags field of the account object.

curl --request GET \
  --url 'https://api.due.network/v1/accounts/<ACCOUNT_ID>' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'accept: application/json'

2. Update account preferences

Send a featureFlags map with the flags you want to set. Each value must be one of require, prefer, discourage, or forbid.

curl --request POST \
  --url 'https://api.due.network/v1/accounts/<ACCOUNT_ID>' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{ "featureFlags": { "swift-named": "require" } }'

You can set several flags in one request:

curl --request POST \
  --url 'https://api.due.network/v1/accounts/<ACCOUNT_ID>' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{ "featureFlags": { "swift-named": "require", "erebor": "prefer" } }'

The API returns the updated account, including its featureFlags.

Provider-routing behavior

Operations that select a channel use the flagged provider according to the value set, provided the channel's feature-flag requirements and the account's eligibility are satisfied. This includes creating new virtual accounts and initiating transfers.

With prefer, routing falls back to another eligible provider if the flagged one cannot be used. With require, it does not: if the flagged provider cannot serve the operation, the operation is not routed to an alternative. Use require only when you specifically need to prevent fallback.

Transactions for virtual accounts that already use an older provider continue to be processed by that provider. Changing an account preference does not move an existing virtual account to a different provider.

Troubleshooting

The account cannot use the preferred provider

Check whether the account has completed the endorsement required by that provider. A provider preference does not replace its eligibility or endorsement requirements.

An operation fails instead of using another provider

Check whether the flag is set to require. require prevents fallback to other providers, so if the flagged provider is unavailable or the account is not eligible for it, the operation fails rather than routing elsewhere. Use prefer if you want fallback behaviour.

Existing virtual-account transactions use a different provider

Existing virtual accounts continue to use their current provider. Create a new virtual account after updating the preference to use the flagged provider for eligible new operations.