> For the complete documentation index, see [llms.txt](https://docs.nexusglobalpayments.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexusglobalpayments.org/apis/fxp-tier-based-improvement.md).

# FXP Tier-based Improvement

## Create an improvement tier

> Creates an improvement tier for a source currency. A tier defines a threshold and an improvement in basis points that applies to your base rate for transactions at or above that threshold. If a live tier already exists for the same source currency and threshold, it is automatically superseded. When Nexus generates a quote, it selects the tier with the greatest threshold that does not exceed the transaction amount, and adds tier and PSP improvements together in basis points before applying them, so improvements never compound. An idempotency key header is recommended. Requires the scope tiers.write. Used by: FX Providers (FXPs)

```json
{"openapi":"3.1.0","info":{"title":"Nexus APIs","version":"0.3.1"},"tags":[{"name":"FXP Tiers","description":"Tier improvement management for FX Providers on the Nexus Config and Admin Portal. A tier gives a better rate, in basis points, for transactions at or above a threshold in a given source currency. Tiers apply to all PSPs equally and remain active until expired. Tiers only need to be set once and continue to apply until they are expired."}],"servers":[{"url":"http://localhost:8080","description":"Local development"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Nexus simulator"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TierInputDto":{"type":"object","description":"Request body for creating a tier. Any live tier that already exists for the same source currency and threshold is automatically superseded.","properties":{"sourceCurrency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency code of the source currency, three uppercase letters."},"threshold":{"type":"number","exclusiveMinimum":0,"description":"Minimum transaction size, in the source currency, at which the tier applies. Must be greater than 0."},"improvementBps":{"type":"integer","minimum":0,"description":"Improvement applied to the base rate, in basis points. Must be greater than or equal to 0."}},"required":["sourceCurrency","threshold","improvementBps"]},"TierDto":{"type":"object","description":"An improvement tier configured by an FXP for a source currency. A tier applies an improvement in basis points to the base rate for transactions at or above its threshold. Tiers apply to all PSPs equally and remain active until expired.","properties":{"tierId":{"type":"string","description":"Unique ID of the tier record."},"fxpId":{"type":"string","description":"ID of the FXP that owns this tier."},"sourceCurrency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency code of the source currency, three uppercase letters."},"threshold":{"type":"number","exclusiveMinimum":0,"description":"Minimum transaction size, in the source currency, at which the tier applies. Must be greater than 0."},"improvementBps":{"type":"integer","minimum":0,"description":"Improvement applied to the base rate, in basis points. Must be greater than or equal to 0."},"createdDateTime":{"type":"string","format":"date-time","description":"Timestamp at which the tier record was created."},"isExpired":{"type":"boolean","description":"Historical marker set to true when the tier is replaced or withdrawn."},"expiryDateTime":{"type":["string","null"],"format":"date-time","description":"Timestamp at which the tier was replaced or withdrawn. A historical marker only."}},"required":["tierId","fxpId","sourceCurrency","threshold","improvementBps","createdDateTime","isExpired"]},"ErrorResultDto":{"type":"object","description":"Structured business rejection returned for all error responses. This response is only returned for rejection cases; the statusCode is always RJCT.","properties":{"statusCode":{"type":"string","enum":["RJCT"],"description":"Business level status code indicating the outcome. Always RJCT (Rejected)."},"reasonCode":{"type":"string","pattern":"^(TE|AE|BE)[A-Z0-9]*$","description":"Categorised reason code with a prefix indicating the error category: TE for Technical Error, AE for Authentication Error, BE for Business Error."},"name":{"type":"string","description":"Machine readable business error name from the error catalogue."},"description":{"type":"string","description":"Human readable error description."}},"required":["statusCode","reasonCode","name","description"]}}},"paths":{"/v1/tiers":{"post":{"summary":"Create an improvement tier","description":"Creates an improvement tier for a source currency. A tier defines a threshold and an improvement in basis points that applies to your base rate for transactions at or above that threshold. If a live tier already exists for the same source currency and threshold, it is automatically superseded. When Nexus generates a quote, it selects the tier with the greatest threshold that does not exceed the transaction amount, and adds tier and PSP improvements together in basis points before applying them, so improvements never compound. An idempotency key header is recommended. Requires the scope tiers.write. Used by: FX Providers (FXPs)","operationId":"createTier","tags":["FXP Tiers"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Recommended for POST requests. A UUID used to deduplicate retried submissions.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TierInputDto"}}}},"responses":{"200":{"description":"The created tier record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TierDto"}}}},"400":{"description":"Invalid request — syntax, schema, or field-level validation failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"403":{"description":"Caller lacks permission for this resource or operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"409":{"description":"Conflicting state (e.g. duplicate tier for the same currency and threshold, or threshold ordering violation).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"429":{"description":"Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry."},"500":{"description":"Unexpected server fault; caller may retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}}}}}}}
```

## List improvement tiers

> Returns the improvement tiers you have configured, with an optional filter by source currency. Each tier gives a better rate, in basis points, for transactions at or above its threshold. Tier records are kept for up to 13 months and a maximum of 100 records is returned. When includeExpired is true, the limit parameter must be provided. Requires the scope tiers.read. Used by: FX Providers (FXPs)

```json
{"openapi":"3.1.0","info":{"title":"Nexus APIs","version":"0.3.1"},"tags":[{"name":"FXP Tiers","description":"Tier improvement management for FX Providers on the Nexus Config and Admin Portal. A tier gives a better rate, in basis points, for transactions at or above a threshold in a given source currency. Tiers apply to all PSPs equally and remain active until expired. Tiers only need to be set once and continue to apply until they are expired."}],"servers":[{"url":"http://localhost:8080","description":"Local development"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Nexus simulator"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TierListDto":{"type":"object","description":"List of tier records belonging to the FXP.","properties":{"tiers":{"type":"array","items":{"$ref":"#/components/schemas/TierDto"}}},"required":["tiers"]},"TierDto":{"type":"object","description":"An improvement tier configured by an FXP for a source currency. A tier applies an improvement in basis points to the base rate for transactions at or above its threshold. Tiers apply to all PSPs equally and remain active until expired.","properties":{"tierId":{"type":"string","description":"Unique ID of the tier record."},"fxpId":{"type":"string","description":"ID of the FXP that owns this tier."},"sourceCurrency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency code of the source currency, three uppercase letters."},"threshold":{"type":"number","exclusiveMinimum":0,"description":"Minimum transaction size, in the source currency, at which the tier applies. Must be greater than 0."},"improvementBps":{"type":"integer","minimum":0,"description":"Improvement applied to the base rate, in basis points. Must be greater than or equal to 0."},"createdDateTime":{"type":"string","format":"date-time","description":"Timestamp at which the tier record was created."},"isExpired":{"type":"boolean","description":"Historical marker set to true when the tier is replaced or withdrawn."},"expiryDateTime":{"type":["string","null"],"format":"date-time","description":"Timestamp at which the tier was replaced or withdrawn. A historical marker only."}},"required":["tierId","fxpId","sourceCurrency","threshold","improvementBps","createdDateTime","isExpired"]},"ErrorResultDto":{"type":"object","description":"Structured business rejection returned for all error responses. This response is only returned for rejection cases; the statusCode is always RJCT.","properties":{"statusCode":{"type":"string","enum":["RJCT"],"description":"Business level status code indicating the outcome. Always RJCT (Rejected)."},"reasonCode":{"type":"string","pattern":"^(TE|AE|BE)[A-Z0-9]*$","description":"Categorised reason code with a prefix indicating the error category: TE for Technical Error, AE for Authentication Error, BE for Business Error."},"name":{"type":"string","description":"Machine readable business error name from the error catalogue."},"description":{"type":"string","description":"Human readable error description."}},"required":["statusCode","reasonCode","name","description"]}}},"paths":{"/v1/tiers":{"get":{"summary":"List improvement tiers","description":"Returns the improvement tiers you have configured, with an optional filter by source currency. Each tier gives a better rate, in basis points, for transactions at or above its threshold. Tier records are kept for up to 13 months and a maximum of 100 records is returned. When includeExpired is true, the limit parameter must be provided. Requires the scope tiers.read. Used by: FX Providers (FXPs)","operationId":"listTiers","tags":["FXP Tiers"],"parameters":[{"name":"sourceCurrency","in":"query","required":false,"description":"ISO 4217 currency code of the source currency, three uppercase letters.","schema":{"type":"string","pattern":"^[A-Z]{3}$"}},{"name":"includeExpired","in":"query","required":false,"description":"If true, include historical records that were replaced or withdrawn in the last 13 months. Default is false. When true, the limit parameter is required. Note that the word expired in field names is historical naming only; records are never expired based on time.","schema":{"type":"boolean","default":false}},{"name":"limit","in":"query","required":false,"description":"Maximum number of items to return. Default is 50 and the maximum is 100. Required when includeExpired is true.","schema":{"type":"integer","default":50,"maximum":100,"minimum":1}}],"responses":{"200":{"description":"The FXP's tiers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TierListDto"}}}},"400":{"description":"Invalid request — syntax, schema, or field-level validation failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"403":{"description":"Caller lacks permission for this resource or operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"429":{"description":"Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry."},"500":{"description":"Unexpected server fault; caller may retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}}}}}}}
```

## Withdraw an improvement tier

> Withdraws a tier so it no longer applies when quotes are generated. The response returns the record with isExpired set to true as a historical marker. Requires the scope tiers.write. Used by: FX Providers (FXPs)

```json
{"openapi":"3.1.0","info":{"title":"Nexus APIs","version":"0.3.1"},"tags":[{"name":"FXP Tiers","description":"Tier improvement management for FX Providers on the Nexus Config and Admin Portal. A tier gives a better rate, in basis points, for transactions at or above a threshold in a given source currency. Tiers apply to all PSPs equally and remain active until expired. Tiers only need to be set once and continue to apply until they are expired."}],"servers":[{"url":"http://localhost:8080","description":"Local development"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Nexus simulator"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TierDto":{"type":"object","description":"An improvement tier configured by an FXP for a source currency. A tier applies an improvement in basis points to the base rate for transactions at or above its threshold. Tiers apply to all PSPs equally and remain active until expired.","properties":{"tierId":{"type":"string","description":"Unique ID of the tier record."},"fxpId":{"type":"string","description":"ID of the FXP that owns this tier."},"sourceCurrency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency code of the source currency, three uppercase letters."},"threshold":{"type":"number","exclusiveMinimum":0,"description":"Minimum transaction size, in the source currency, at which the tier applies. Must be greater than 0."},"improvementBps":{"type":"integer","minimum":0,"description":"Improvement applied to the base rate, in basis points. Must be greater than or equal to 0."},"createdDateTime":{"type":"string","format":"date-time","description":"Timestamp at which the tier record was created."},"isExpired":{"type":"boolean","description":"Historical marker set to true when the tier is replaced or withdrawn."},"expiryDateTime":{"type":["string","null"],"format":"date-time","description":"Timestamp at which the tier was replaced or withdrawn. A historical marker only."}},"required":["tierId","fxpId","sourceCurrency","threshold","improvementBps","createdDateTime","isExpired"]},"ErrorResultDto":{"type":"object","description":"Structured business rejection returned for all error responses. This response is only returned for rejection cases; the statusCode is always RJCT.","properties":{"statusCode":{"type":"string","enum":["RJCT"],"description":"Business level status code indicating the outcome. Always RJCT (Rejected)."},"reasonCode":{"type":"string","pattern":"^(TE|AE|BE)[A-Z0-9]*$","description":"Categorised reason code with a prefix indicating the error category: TE for Technical Error, AE for Authentication Error, BE for Business Error."},"name":{"type":"string","description":"Machine readable business error name from the error catalogue."},"description":{"type":"string","description":"Human readable error description."}},"required":["statusCode","reasonCode","name","description"]}}},"paths":{"/v1/tiers/{tierId}":{"delete":{"summary":"Withdraw an improvement tier","description":"Withdraws a tier so it no longer applies when quotes are generated. The response returns the record with isExpired set to true as a historical marker. Requires the scope tiers.write. Used by: FX Providers (FXPs)","operationId":"withdrawTier","tags":["FXP Tiers"],"parameters":[{"name":"tierId","in":"path","required":true,"description":"UUID of the tier record.","schema":{"type":"string"}}],"responses":{"200":{"description":"The withdrawn tier record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TierDto"}}}},"400":{"description":"Invalid request — syntax, schema, or field-level validation failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"403":{"description":"Caller lacks permission for this resource or operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"404":{"description":"Tier not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"429":{"description":"Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry."},"500":{"description":"Unexpected server fault; caller may retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}}}}}}}
```

## Count improvement tiers

> Returns the number of tier records you have configured. Set includeExpired to true to include expired tiers in the count. Requires the scope tiers.read. Used by: FX Providers (FXPs)

```json
{"openapi":"3.1.0","info":{"title":"Nexus APIs","version":"0.3.1"},"tags":[{"name":"FXP Tiers","description":"Tier improvement management for FX Providers on the Nexus Config and Admin Portal. A tier gives a better rate, in basis points, for transactions at or above a threshold in a given source currency. Tiers apply to all PSPs equally and remain active until expired. Tiers only need to be set once and continue to apply until they are expired."}],"servers":[{"url":"http://localhost:8080","description":"Local development"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Nexus simulator"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"CountDto":{"type":"object","description":"A simple record count.","properties":{"count":{"type":"integer","description":"The number of records."}},"required":["count"]},"ErrorResultDto":{"type":"object","description":"Structured business rejection returned for all error responses. This response is only returned for rejection cases; the statusCode is always RJCT.","properties":{"statusCode":{"type":"string","enum":["RJCT"],"description":"Business level status code indicating the outcome. Always RJCT (Rejected)."},"reasonCode":{"type":"string","pattern":"^(TE|AE|BE)[A-Z0-9]*$","description":"Categorised reason code with a prefix indicating the error category: TE for Technical Error, AE for Authentication Error, BE for Business Error."},"name":{"type":"string","description":"Machine readable business error name from the error catalogue."},"description":{"type":"string","description":"Human readable error description."}},"required":["statusCode","reasonCode","name","description"]}}},"paths":{"/v1/tiers/count":{"get":{"summary":"Count improvement tiers","description":"Returns the number of tier records you have configured. Set includeExpired to true to include expired tiers in the count. Requires the scope tiers.read. Used by: FX Providers (FXPs)","operationId":"getTiersCount","tags":["FXP Tiers"],"parameters":[{"name":"includeExpired","in":"query","required":false,"description":"If true, include historical records that were replaced or withdrawn in the last 13 months. Default is false. When true, the limit parameter is required. Note that the word expired in field names is historical naming only; records are never expired based on time.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"The tier record count.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountDto"}}}},"400":{"description":"Invalid request — syntax, schema, or field-level validation failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"403":{"description":"Caller lacks permission for this resource or operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"429":{"description":"Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry."},"500":{"description":"Unexpected server fault; caller may retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}}}}}}}
```

## Get an improvement tier

> Returns a single tier record by its id. Requires the scope tiers.read. Used by: FX Providers (FXPs)

```json
{"openapi":"3.1.0","info":{"title":"Nexus APIs","version":"0.3.1"},"tags":[{"name":"FXP Tiers","description":"Tier improvement management for FX Providers on the Nexus Config and Admin Portal. A tier gives a better rate, in basis points, for transactions at or above a threshold in a given source currency. Tiers apply to all PSPs equally and remain active until expired. Tiers only need to be set once and continue to apply until they are expired."}],"servers":[{"url":"http://localhost:8080","description":"Local development"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Nexus simulator"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TierDto":{"type":"object","description":"An improvement tier configured by an FXP for a source currency. A tier applies an improvement in basis points to the base rate for transactions at or above its threshold. Tiers apply to all PSPs equally and remain active until expired.","properties":{"tierId":{"type":"string","description":"Unique ID of the tier record."},"fxpId":{"type":"string","description":"ID of the FXP that owns this tier."},"sourceCurrency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency code of the source currency, three uppercase letters."},"threshold":{"type":"number","exclusiveMinimum":0,"description":"Minimum transaction size, in the source currency, at which the tier applies. Must be greater than 0."},"improvementBps":{"type":"integer","minimum":0,"description":"Improvement applied to the base rate, in basis points. Must be greater than or equal to 0."},"createdDateTime":{"type":"string","format":"date-time","description":"Timestamp at which the tier record was created."},"isExpired":{"type":"boolean","description":"Historical marker set to true when the tier is replaced or withdrawn."},"expiryDateTime":{"type":["string","null"],"format":"date-time","description":"Timestamp at which the tier was replaced or withdrawn. A historical marker only."}},"required":["tierId","fxpId","sourceCurrency","threshold","improvementBps","createdDateTime","isExpired"]},"ErrorResultDto":{"type":"object","description":"Structured business rejection returned for all error responses. This response is only returned for rejection cases; the statusCode is always RJCT.","properties":{"statusCode":{"type":"string","enum":["RJCT"],"description":"Business level status code indicating the outcome. Always RJCT (Rejected)."},"reasonCode":{"type":"string","pattern":"^(TE|AE|BE)[A-Z0-9]*$","description":"Categorised reason code with a prefix indicating the error category: TE for Technical Error, AE for Authentication Error, BE for Business Error."},"name":{"type":"string","description":"Machine readable business error name from the error catalogue."},"description":{"type":"string","description":"Human readable error description."}},"required":["statusCode","reasonCode","name","description"]}}},"paths":{"/v1/tiers/{tierId}":{"get":{"summary":"Get an improvement tier","description":"Returns a single tier record by its id. Requires the scope tiers.read. Used by: FX Providers (FXPs)","operationId":"getTier","tags":["FXP Tiers"],"parameters":[{"name":"tierId","in":"path","required":true,"description":"UUID of the tier record.","schema":{"type":"string"}}],"responses":{"200":{"description":"The tier record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TierDto"}}}},"400":{"description":"Invalid request — syntax, schema, or field-level validation failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"403":{"description":"Caller lacks permission for this resource or operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"404":{"description":"Tier not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"429":{"description":"Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry."},"500":{"description":"Unexpected server fault; caller may retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}}}}}}}
```