> 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 or replace a tier

> Creates a new tier record for the given source currency and threshold. If a live tier already exists for the same fxpId, sourceCurrency, and threshold, Nexus marks the prior record as superseded and creates the new tier. Tiers are PSP-agnostic and apply based on transaction size in the source currency.

```json
{"openapi":"3.1.0","info":{"title":"Nexus API","version":"v1"},"tags":[{"name":"FXP Tier Improvements","description":"Manage tier-based rate improvements per source currency. Tiers apply a basis-point improvement for transactions meeting or exceeding a threshold amount. Nexus selects the tier with the greatest qualifying threshold and combines it with any applicable PSP-based improvement before applying the total to the base rate."}],"servers":[{"url":"http://localhost:8080","description":"Local simulator (make run / make docker-run)"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Deployed simulator (Cloud Run, asia-southeast1) - indicative, not authoritative"}],"security":[{"nexusClientCert":[],"nexusOAuth":["tiers.write"]}],"components":{"securitySchemes":{"nexusClientCert":{"type":"mutualTLS","description":"Nexus issued X.509 client certificate presented during the TLS handshake and validated at the Akamai global edge. The FXP generates its own key pair and submits a CSR during onboarding; Vault PKI (edge intermediate CA) signs it and the private key never leaves FXP infrastructure. Fail closed: a missing, expired, revoked or untrusted certificate causes the TLS handshake to fail at the edge and no HTTP response is produced. The certificate is not forwarded to the origin as an HTTP header."}},"schemas":{"TierRequest":{"type":"object","required":["sourceCurrency","threshold","improvementBps"],"description":"Request body for creating or replacing a tier.","properties":{"sourceCurrency":{"type":"string","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$","description":"ISO 4217 source currency code the tier applies to."},"threshold":{"type":"number","format":"double","exclusiveMinimum":0,"description":"Minimum transaction amount in the source currency for this tier to apply."},"improvementBps":{"type":"integer","minimum":1,"description":"Rate improvement in basis points applied to the base rate when this tier is selected."}}},"TierResponse":{"type":"object","description":"A single FXP tier record.","properties":{"tierId":{"type":"string","format":"uuid","description":"Nexus-assigned unique identifier for the tier record."},"fxpId":{"type":"string","description":"Nexus internal identifier for the FXP that owns this tier."},"sourceCurrency":{"type":"string","maxLength":3,"minLength":3,"description":"ISO 4217 source currency code this tier applies to."},"threshold":{"type":"number","format":"double","description":"Minimum transaction amount (in source currency) for this tier to apply."},"improvementBps":{"type":"integer","description":"Improvement in basis points applied when this tier is selected."},"createdDateTime":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp when this tier record was created."},"isExpired":{"type":"boolean","description":"If true, this tier has been superseded or voluntarily withdrawn."},"expiryDateTime":{"type":["string","null"],"format":"date-time","description":"ISO 8601 UTC timestamp when this tier was superseded or withdrawn. Null if still live."}}},"ErrorApiResponse":{"type":"object","description":"Standard structured rejection body. Returned for all non-2xx responses produced by the auth sidecar or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.","properties":{"statusCode":{"type":"string","description":"Business-level status code. Always RJCT (Rejected) — the structured error body is only returned for rejection cases. Successful responses use HTTP status alone (200 OK for sync, 202 Accepted for async ingress) with no structured statusCode body.","enum":["RJCT"],"maxLength":4},"reasonCode":{"type":"string","description":"Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE002/TE099), AE (Authentication / Authorization Error, e.g. AE001–AE004, sidecar-enforced), BE (Business Error). BE001–BE020 are raised by the Payments endpoints; BE021–BE027 are raised by the FXP endpoints.","enum":["AE001","AE002","AE003","AE004","BE001","BE002","BE005","BE006","BE007","BE008","BE009","BE011","BE012","BE016","BE017","BE018","BE019","BE020","BE021","BE022","BE023","BE024","BE025","BE026","BE027","TE001","TE002","TE099"],"maxLength":5,"pattern":"[A-Z]{2}[0-9]{3}"},"name":{"type":"string","description":"Machine-readable business error name from the reason code catalogue.","maxLength":50,"pattern":"[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*"},"description":{"type":"string","description":"Human-readable error description. MUST NOT contain PII (CD-INV-09).","maxLength":500}},"required":["description","name","reasonCode","statusCode"]}}},"paths":{"/v1/tiers":{"post":{"tags":["FXP Tier Improvements"],"summary":"Create or replace a tier","description":"Creates a new tier record for the given source currency and threshold. If a live tier already exists for the same fxpId, sourceCurrency, and threshold, Nexus marks the prior record as superseded and creates the new tier. Tiers are PSP-agnostic and apply based on transaction size in the source currency.","operationId":"createTier","parameters":[{"name":"Accept","in":"header","description":"application/json","required":true,"schema":{"type":"string","default":"application/json"}}],"requestBody":{"description":"Tier creation request.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TierRequest"}}}},"responses":{"200":{"description":"Tier created successfully. Returns the new tier record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TierResponse"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"401":{"description":"Authentication Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"403":{"description":"Authorization Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"405":{"description":"Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.","headers":{"Allow":{"description":"Permitted HTTP methods for this endpoint","schema":{"type":"string"}}}},"409":{"description":"Conflict. The tier could not be created due to a conflicting state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"429":{"description":"Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.","headers":{"Retry-After":{"description":"Duration after which the caller may retry","schema":{"type":"integer","minimum":0,"description":"Number of seconds to wait before retrying"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"502":{"description":"Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate."},"503":{"description":"Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff."},"504":{"description":"Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff."}}}}}}
```

## List FXP tiers

> Returns the authenticated FXP's configured tiers, optionally filtered by source currency. When includeExpired=true, historical tiers from the last 13 months are included and limit is required (maximum 100). Tiers remain live until replaced for the same (fxpId, sourceCurrency, threshold) or voluntarily withdrawn.

```json
{"openapi":"3.1.0","info":{"title":"Nexus API","version":"v1"},"tags":[{"name":"FXP Tier Improvements","description":"Manage tier-based rate improvements per source currency. Tiers apply a basis-point improvement for transactions meeting or exceeding a threshold amount. Nexus selects the tier with the greatest qualifying threshold and combines it with any applicable PSP-based improvement before applying the total to the base rate."}],"servers":[{"url":"http://localhost:8080","description":"Local simulator (make run / make docker-run)"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Deployed simulator (Cloud Run, asia-southeast1) - indicative, not authoritative"}],"security":[{"nexusClientCert":[],"nexusOAuth":["tiers.read"]}],"components":{"securitySchemes":{"nexusClientCert":{"type":"mutualTLS","description":"Nexus issued X.509 client certificate presented during the TLS handshake and validated at the Akamai global edge. The FXP generates its own key pair and submits a CSR during onboarding; Vault PKI (edge intermediate CA) signs it and the private key never leaves FXP infrastructure. Fail closed: a missing, expired, revoked or untrusted certificate causes the TLS handshake to fail at the edge and no HTTP response is produced. The certificate is not forwarded to the origin as an HTTP header."}},"schemas":{"TiersPageResponse":{"type":"object","description":"Paginated list of tier records.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TierResponse"},"description":"Tier records for the current page."},"cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Null if this is the last page."}}},"TierResponse":{"type":"object","description":"A single FXP tier record.","properties":{"tierId":{"type":"string","format":"uuid","description":"Nexus-assigned unique identifier for the tier record."},"fxpId":{"type":"string","description":"Nexus internal identifier for the FXP that owns this tier."},"sourceCurrency":{"type":"string","maxLength":3,"minLength":3,"description":"ISO 4217 source currency code this tier applies to."},"threshold":{"type":"number","format":"double","description":"Minimum transaction amount (in source currency) for this tier to apply."},"improvementBps":{"type":"integer","description":"Improvement in basis points applied when this tier is selected."},"createdDateTime":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp when this tier record was created."},"isExpired":{"type":"boolean","description":"If true, this tier has been superseded or voluntarily withdrawn."},"expiryDateTime":{"type":["string","null"],"format":"date-time","description":"ISO 8601 UTC timestamp when this tier was superseded or withdrawn. Null if still live."}}},"ErrorApiResponse":{"type":"object","description":"Standard structured rejection body. Returned for all non-2xx responses produced by the auth sidecar or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.","properties":{"statusCode":{"type":"string","description":"Business-level status code. Always RJCT (Rejected) — the structured error body is only returned for rejection cases. Successful responses use HTTP status alone (200 OK for sync, 202 Accepted for async ingress) with no structured statusCode body.","enum":["RJCT"],"maxLength":4},"reasonCode":{"type":"string","description":"Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE002/TE099), AE (Authentication / Authorization Error, e.g. AE001–AE004, sidecar-enforced), BE (Business Error). BE001–BE020 are raised by the Payments endpoints; BE021–BE027 are raised by the FXP endpoints.","enum":["AE001","AE002","AE003","AE004","BE001","BE002","BE005","BE006","BE007","BE008","BE009","BE011","BE012","BE016","BE017","BE018","BE019","BE020","BE021","BE022","BE023","BE024","BE025","BE026","BE027","TE001","TE002","TE099"],"maxLength":5,"pattern":"[A-Z]{2}[0-9]{3}"},"name":{"type":"string","description":"Machine-readable business error name from the reason code catalogue.","maxLength":50,"pattern":"[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*"},"description":{"type":"string","description":"Human-readable error description. MUST NOT contain PII (CD-INV-09).","maxLength":500}},"required":["description","name","reasonCode","statusCode"]}}},"paths":{"/v1/tiers":{"get":{"tags":["FXP Tier Improvements"],"summary":"List FXP tiers","description":"Returns the authenticated FXP's configured tiers, optionally filtered by source currency. When includeExpired=true, historical tiers from the last 13 months are included and limit is required (maximum 100). Tiers remain live until replaced for the same (fxpId, sourceCurrency, threshold) or voluntarily withdrawn.","operationId":"listTiers","parameters":[{"name":"Accept","in":"header","description":"application/json","required":true,"schema":{"type":"string","default":"application/json"}},{"name":"sourceCurrency","in":"query","description":"ISO 4217 3-letter source currency code (uppercase). Filters results to tiers for this source currency.","required":false,"schema":{"type":"string","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"}},{"name":"includeExpired","in":"query","description":"If true, include expired (withdrawn or superseded) tiers from the last 13 months. Default: false. When true, limit is required.","required":false,"schema":{"type":"boolean","default":false}},{"name":"limit","in":"query","description":"Max items to return. Default 50. Maximum 100. Required when includeExpired=true.","required":false,"schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"Pagination cursor; omit for first page. This endpoint is limited to a maximum of 100 records.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tiers retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiersPageResponse"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"401":{"description":"Authentication Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"403":{"description":"Authorization Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"405":{"description":"Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.","headers":{"Allow":{"description":"Permitted HTTP methods for this endpoint","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.","headers":{"Retry-After":{"description":"Duration after which the caller may retry","schema":{"type":"integer","minimum":0,"description":"Number of seconds to wait before retrying"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"502":{"description":"Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate."},"503":{"description":"Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff."},"504":{"description":"Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff."}}}}}}
```

## Withdraw a tier

> Voluntarily withdraws a tier so it no longer applies to quote generation. Sets isExpired=true and records expiryDateTime as a historical marker. Returns the withdrawn tier record.

```json
{"openapi":"3.1.0","info":{"title":"Nexus API","version":"v1"},"tags":[{"name":"FXP Tier Improvements","description":"Manage tier-based rate improvements per source currency. Tiers apply a basis-point improvement for transactions meeting or exceeding a threshold amount. Nexus selects the tier with the greatest qualifying threshold and combines it with any applicable PSP-based improvement before applying the total to the base rate."}],"servers":[{"url":"http://localhost:8080","description":"Local simulator (make run / make docker-run)"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Deployed simulator (Cloud Run, asia-southeast1) - indicative, not authoritative"}],"security":[{"nexusClientCert":[],"nexusOAuth":["tiers.write"]}],"components":{"securitySchemes":{"nexusClientCert":{"type":"mutualTLS","description":"Nexus issued X.509 client certificate presented during the TLS handshake and validated at the Akamai global edge. The FXP generates its own key pair and submits a CSR during onboarding; Vault PKI (edge intermediate CA) signs it and the private key never leaves FXP infrastructure. Fail closed: a missing, expired, revoked or untrusted certificate causes the TLS handshake to fail at the edge and no HTTP response is produced. The certificate is not forwarded to the origin as an HTTP header."}},"schemas":{"TierResponse":{"type":"object","description":"A single FXP tier record.","properties":{"tierId":{"type":"string","format":"uuid","description":"Nexus-assigned unique identifier for the tier record."},"fxpId":{"type":"string","description":"Nexus internal identifier for the FXP that owns this tier."},"sourceCurrency":{"type":"string","maxLength":3,"minLength":3,"description":"ISO 4217 source currency code this tier applies to."},"threshold":{"type":"number","format":"double","description":"Minimum transaction amount (in source currency) for this tier to apply."},"improvementBps":{"type":"integer","description":"Improvement in basis points applied when this tier is selected."},"createdDateTime":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp when this tier record was created."},"isExpired":{"type":"boolean","description":"If true, this tier has been superseded or voluntarily withdrawn."},"expiryDateTime":{"type":["string","null"],"format":"date-time","description":"ISO 8601 UTC timestamp when this tier was superseded or withdrawn. Null if still live."}}},"ErrorApiResponse":{"type":"object","description":"Standard structured rejection body. Returned for all non-2xx responses produced by the auth sidecar or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.","properties":{"statusCode":{"type":"string","description":"Business-level status code. Always RJCT (Rejected) — the structured error body is only returned for rejection cases. Successful responses use HTTP status alone (200 OK for sync, 202 Accepted for async ingress) with no structured statusCode body.","enum":["RJCT"],"maxLength":4},"reasonCode":{"type":"string","description":"Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE002/TE099), AE (Authentication / Authorization Error, e.g. AE001–AE004, sidecar-enforced), BE (Business Error). BE001–BE020 are raised by the Payments endpoints; BE021–BE027 are raised by the FXP endpoints.","enum":["AE001","AE002","AE003","AE004","BE001","BE002","BE005","BE006","BE007","BE008","BE009","BE011","BE012","BE016","BE017","BE018","BE019","BE020","BE021","BE022","BE023","BE024","BE025","BE026","BE027","TE001","TE002","TE099"],"maxLength":5,"pattern":"[A-Z]{2}[0-9]{3}"},"name":{"type":"string","description":"Machine-readable business error name from the reason code catalogue.","maxLength":50,"pattern":"[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*"},"description":{"type":"string","description":"Human-readable error description. MUST NOT contain PII (CD-INV-09).","maxLength":500}},"required":["description","name","reasonCode","statusCode"]}}},"paths":{"/v1/tiers/{tierId}":{"delete":{"tags":["FXP Tier Improvements"],"summary":"Withdraw a tier","description":"Voluntarily withdraws a tier so it no longer applies to quote generation. Sets isExpired=true and records expiryDateTime as a historical marker. Returns the withdrawn tier record.","operationId":"withdrawTier","parameters":[{"name":"Accept","in":"header","description":"application/json","required":true,"schema":{"type":"string","default":"application/json"}},{"name":"tierId","in":"path","description":"UUID of the tier record to withdraw.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Tier withdrawn successfully. Returns the withdrawn tier record with isExpired=true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TierResponse"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"401":{"description":"Authentication Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"403":{"description":"Authorization Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"404":{"description":"Tier Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"405":{"description":"Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.","headers":{"Allow":{"description":"Permitted HTTP methods for this endpoint","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.","headers":{"Retry-After":{"description":"Duration after which the caller may retry","schema":{"type":"integer","minimum":0,"description":"Number of seconds to wait before retrying"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"502":{"description":"Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate."},"503":{"description":"Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff."},"504":{"description":"Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff."}}}}}}
```

## Get tier count

> Returns the count of tiers for the authenticated FXP. includeExpired controls whether expired (withdrawn or superseded) tiers are included in the count.

```json
{"openapi":"3.1.0","info":{"title":"Nexus API","version":"v1"},"tags":[{"name":"FXP Tier Improvements","description":"Manage tier-based rate improvements per source currency. Tiers apply a basis-point improvement for transactions meeting or exceeding a threshold amount. Nexus selects the tier with the greatest qualifying threshold and combines it with any applicable PSP-based improvement before applying the total to the base rate."}],"servers":[{"url":"http://localhost:8080","description":"Local simulator (make run / make docker-run)"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Deployed simulator (Cloud Run, asia-southeast1) - indicative, not authoritative"}],"security":[{"nexusClientCert":[],"nexusOAuth":["tiers.read"]}],"components":{"securitySchemes":{"nexusClientCert":{"type":"mutualTLS","description":"Nexus issued X.509 client certificate presented during the TLS handshake and validated at the Akamai global edge. The FXP generates its own key pair and submits a CSR during onboarding; Vault PKI (edge intermediate CA) signs it and the private key never leaves FXP infrastructure. Fail closed: a missing, expired, revoked or untrusted certificate causes the TLS handshake to fail at the edge and no HTTP response is produced. The certificate is not forwarded to the origin as an HTTP header."}},"schemas":{"CountResponse":{"type":"object","description":"Count of records matching the query.","properties":{"count":{"type":"integer","minimum":0,"description":"Total count of matching records."}}},"ErrorApiResponse":{"type":"object","description":"Standard structured rejection body. Returned for all non-2xx responses produced by the auth sidecar or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.","properties":{"statusCode":{"type":"string","description":"Business-level status code. Always RJCT (Rejected) — the structured error body is only returned for rejection cases. Successful responses use HTTP status alone (200 OK for sync, 202 Accepted for async ingress) with no structured statusCode body.","enum":["RJCT"],"maxLength":4},"reasonCode":{"type":"string","description":"Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE002/TE099), AE (Authentication / Authorization Error, e.g. AE001–AE004, sidecar-enforced), BE (Business Error). BE001–BE020 are raised by the Payments endpoints; BE021–BE027 are raised by the FXP endpoints.","enum":["AE001","AE002","AE003","AE004","BE001","BE002","BE005","BE006","BE007","BE008","BE009","BE011","BE012","BE016","BE017","BE018","BE019","BE020","BE021","BE022","BE023","BE024","BE025","BE026","BE027","TE001","TE002","TE099"],"maxLength":5,"pattern":"[A-Z]{2}[0-9]{3}"},"name":{"type":"string","description":"Machine-readable business error name from the reason code catalogue.","maxLength":50,"pattern":"[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*"},"description":{"type":"string","description":"Human-readable error description. MUST NOT contain PII (CD-INV-09).","maxLength":500}},"required":["description","name","reasonCode","statusCode"]}}},"paths":{"/v1/tiers/count":{"get":{"tags":["FXP Tier Improvements"],"summary":"Get tier count","description":"Returns the count of tiers for the authenticated FXP. includeExpired controls whether expired (withdrawn or superseded) tiers are included in the count.","operationId":"getTierCount","parameters":[{"name":"Accept","in":"header","description":"application/json","required":true,"schema":{"type":"string","default":"application/json"}},{"name":"includeExpired","in":"query","description":"If true, include expired (withdrawn or superseded) tiers in the count. Default: false.","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Count retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountResponse"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"401":{"description":"Authentication Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"403":{"description":"Authorization Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"405":{"description":"Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.","headers":{"Allow":{"description":"Permitted HTTP methods for this endpoint","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.","headers":{"Retry-After":{"description":"Duration after which the caller may retry","schema":{"type":"integer","minimum":0,"description":"Number of seconds to wait before retrying"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"502":{"description":"Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate."},"503":{"description":"Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff."},"504":{"description":"Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff."}}}}}}
```

## Get a single tier

> Returns a single tier record by tierId for the authenticated FXP.

```json
{"openapi":"3.1.0","info":{"title":"Nexus API","version":"v1"},"tags":[{"name":"FXP Tier Improvements","description":"Manage tier-based rate improvements per source currency. Tiers apply a basis-point improvement for transactions meeting or exceeding a threshold amount. Nexus selects the tier with the greatest qualifying threshold and combines it with any applicable PSP-based improvement before applying the total to the base rate."}],"servers":[{"url":"http://localhost:8080","description":"Local simulator (make run / make docker-run)"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Deployed simulator (Cloud Run, asia-southeast1) - indicative, not authoritative"}],"security":[{"nexusClientCert":[],"nexusOAuth":["tiers.read"]}],"components":{"securitySchemes":{"nexusClientCert":{"type":"mutualTLS","description":"Nexus issued X.509 client certificate presented during the TLS handshake and validated at the Akamai global edge. The FXP generates its own key pair and submits a CSR during onboarding; Vault PKI (edge intermediate CA) signs it and the private key never leaves FXP infrastructure. Fail closed: a missing, expired, revoked or untrusted certificate causes the TLS handshake to fail at the edge and no HTTP response is produced. The certificate is not forwarded to the origin as an HTTP header."}},"schemas":{"TierResponse":{"type":"object","description":"A single FXP tier record.","properties":{"tierId":{"type":"string","format":"uuid","description":"Nexus-assigned unique identifier for the tier record."},"fxpId":{"type":"string","description":"Nexus internal identifier for the FXP that owns this tier."},"sourceCurrency":{"type":"string","maxLength":3,"minLength":3,"description":"ISO 4217 source currency code this tier applies to."},"threshold":{"type":"number","format":"double","description":"Minimum transaction amount (in source currency) for this tier to apply."},"improvementBps":{"type":"integer","description":"Improvement in basis points applied when this tier is selected."},"createdDateTime":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp when this tier record was created."},"isExpired":{"type":"boolean","description":"If true, this tier has been superseded or voluntarily withdrawn."},"expiryDateTime":{"type":["string","null"],"format":"date-time","description":"ISO 8601 UTC timestamp when this tier was superseded or withdrawn. Null if still live."}}},"ErrorApiResponse":{"type":"object","description":"Standard structured rejection body. Returned for all non-2xx responses produced by the auth sidecar or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.","properties":{"statusCode":{"type":"string","description":"Business-level status code. Always RJCT (Rejected) — the structured error body is only returned for rejection cases. Successful responses use HTTP status alone (200 OK for sync, 202 Accepted for async ingress) with no structured statusCode body.","enum":["RJCT"],"maxLength":4},"reasonCode":{"type":"string","description":"Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE002/TE099), AE (Authentication / Authorization Error, e.g. AE001–AE004, sidecar-enforced), BE (Business Error). BE001–BE020 are raised by the Payments endpoints; BE021–BE027 are raised by the FXP endpoints.","enum":["AE001","AE002","AE003","AE004","BE001","BE002","BE005","BE006","BE007","BE008","BE009","BE011","BE012","BE016","BE017","BE018","BE019","BE020","BE021","BE022","BE023","BE024","BE025","BE026","BE027","TE001","TE002","TE099"],"maxLength":5,"pattern":"[A-Z]{2}[0-9]{3}"},"name":{"type":"string","description":"Machine-readable business error name from the reason code catalogue.","maxLength":50,"pattern":"[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*"},"description":{"type":"string","description":"Human-readable error description. MUST NOT contain PII (CD-INV-09).","maxLength":500}},"required":["description","name","reasonCode","statusCode"]}}},"paths":{"/v1/tiers/{tierId}":{"get":{"tags":["FXP Tier Improvements"],"summary":"Get a single tier","description":"Returns a single tier record by tierId for the authenticated FXP.","operationId":"getTier","parameters":[{"name":"Accept","in":"header","description":"application/json","required":true,"schema":{"type":"string","default":"application/json"}},{"name":"tierId","in":"path","description":"UUID of the tier record.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Tier retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TierResponse"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"401":{"description":"Authentication Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"403":{"description":"Authorization Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"404":{"description":"Tier Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"405":{"description":"Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.","headers":{"Allow":{"description":"Permitted HTTP methods for this endpoint","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.","headers":{"Retry-After":{"description":"Duration after which the caller may retry","schema":{"type":"integer","minimum":0,"description":"Number of seconds to wait before retrying"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"502":{"description":"Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate."},"503":{"description":"Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff."},"504":{"description":"Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff."}}}}}}
```