---
title: "Create an improvement tier"
method: POST
path: "/v1/tiers"
tags: ["FXP Tiers"]
---

# Create an improvement tier

`POST /v1/tiers`

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)

## Headers

- `Idempotency-Key` string, uuid

## Request body

- TierInputDto — Request body for creating a tier. Any live tier that already exists for the same source currency and threshold is automatically superseded.
  - `sourceCurrency` string, required — ISO 4217 currency code of the source currency, three uppercase letters.
  - `threshold` number, required — Minimum transaction size, in the source currency, at which the tier applies. Must be greater than 0.
  - `improvementBps` integer, required — Improvement applied to the base rate, in basis points. Must be greater than or equal to 0.

## Response `200`

The created tier record.

- TierDto — 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.
  - `tierId` string, required — Unique ID of the tier record.
  - `fxpId` string, required — ID of the FXP that owns this tier.
  - `sourceCurrency` string, required — ISO 4217 currency code of the source currency, three uppercase letters.
  - `threshold` number, required — Minimum transaction size, in the source currency, at which the tier applies. Must be greater than 0.
  - `improvementBps` integer, required — Improvement applied to the base rate, in basis points. Must be greater than or equal to 0.
  - `createdDateTime` string, date-time, required — Timestamp at which the tier record was created.
  - `isExpired` boolean, required — Historical marker set to true when the tier is replaced or withdrawn.
  - `expiryDateTime` string, date-time, nullable — Timestamp at which the tier was replaced or withdrawn. A historical marker only.

## Other responses

- `400` — Invalid request — syntax, schema, or field-level validation failure.
- `401` — Missing or invalid bearer token.
- `403` — Caller lacks permission for this resource or operation.
- `409` — Conflicting state (e.g. duplicate tier for the same currency and threshold, or threshold ordering violation).
- `429` — Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry.
- `500` — Unexpected server fault; caller may retry.

---

[API](https://skmtc.net/nexusglobalpayments/apis/nexus-apis.md) · [All operations](https://skmtc.net/nexusglobalpayments/apis/nexus-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nexusglobalpayments/nexus-apis/revisions/b3e625f21841/schema)