Create FX tariff fee range

Creates a fee range. Answers 200 with the created row, not 201. Amounts are INTEGER MINOR units; percent_fee is a decimal rate between 0 and 1 and IS validated, so 1.5 is rejected with 400.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Body of POST and PUT /v1/fx/tariffs/fees[/{id}] (models.FxTariffFeeInput). The previous spec pointed these at the RESPONSE schema. active is not part of this struct — it lives on BaseModel and the handler applies it separately when present.

min_range?integer

Lower bound of the amount band. INTEGER MINOR UNITS of the currency being converted, stored and returned unscaled. The v1 convert response reports the same field in major units instead — see fee_range there. Carries omitempty in Go, so it is ABSENT from the response when it is zero — not present as 0. A first band with min_range 0, a percentage method (fixed_fee 0) and no floor or cap (min_fee 0, max_fee 0) therefore comes back with four of the six pricing keys missing, and "no cap" is indistinguishable from "not sent".

max_range?integer

Upper bound of the amount band. INTEGER MINOR UNITS of the currency being converted, stored and returned unscaled. The v1 convert response reports the same field in major units instead — see fee_range there. Carries omitempty in Go, so it is ABSENT from the response when it is zero — not present as 0. A first band with min_range 0, a percentage method (fixed_fee 0) and no floor or cap (min_fee 0, max_fee 0) therefore comes back with four of the six pricing keys missing, and "no cap" is indistinguishable from "not sent".

fixed_fee?integer

INTEGER MINOR UNITS of the currency being converted, stored and returned unscaled. The v1 convert response reports the same field in major units instead — see fee_range there. Carries omitempty in Go, so it is ABSENT from the response when it is zero — not present as 0. A first band with min_range 0, a percentage method (fixed_fee 0) and no floor or cap (min_fee 0, max_fee 0) therefore comes back with four of the six pricing keys missing, and "no cap" is indistinguishable from "not sent".

percent_fee?number

Decimal rate, NOT a percentage and NOT scaled: 0.01 means 1%. This is the one field in the module with a live validate tag (gte=0,lte=1), so a value above 1 really is rejected with 400. Carries omitempty in Go, so it is ABSENT from the response when it is zero — not present as 0. A first band with min_range 0, a percentage method (fixed_fee 0) and no floor or cap (min_fee 0, max_fee 0) therefore comes back with four of the six pricing keys missing, and "no cap" is indistinguishable from "not sent".

min_fee?integer

max_fee?integer

method?string

Fee calculation method, matched case-sensitively against models.FeeCalculationMethod. FX does NOT validate this field — unlike modules/tariffs, which guards the same column with validate:"required,oneof=fixed percentage greater lesser sum". Any other value is stored as given and then misses every case in commonutil.CalculateFeeMinor, whose default branch returns fixed_fee — so an unlisted method silently prices as "fixed" forever, with no error at any point. Carries omitempty in Go, so it is ABSENT from the response when it is the empty string. A first band with min_range 0, a percentage method (fixed_fee 0) and no floor or cap (min_fee 0, max_fee 0) therefore comes back with four of the six pricing keys missing, and "no cap" is indistinguishable from "not sent".

base_currency?|

The currency's ID, NOT its ISO code. fx.fee_ranges.base_currency is a uuid column with a foreign key to currencies; the Go field is a *string only because it is read back as text, and nothing in the handler resolves a code — a body carrying "EUR" is refused by the database. Contrast POST /v2/fx/spreads, which does resolve a code on the way in and renders one on the way out.

ALL OR NOTHING, AND SCOPING A RANGE TO A PAIR HAS NO EFFECT TODAY. The CHECK constraint chk_fee_ranges_currency_pair accepts a row only when both currencies are NULL or both are set, so a range scoped to one side alone cannot be stored. A range with both set is stored and then never selected: findApplicableFeeRange compares the stored id against the transaction's ISO code, so its steps 3 to 5 never match and every conversion falls through to step 6, the range with both columns NULL. Leave both NULL until that is fixed.

target_currency?|

The currency's ID, not its ISO code — see base_currency.

fx_tariff_id?string

fx_tariff_id. The Go tag carries omitempty, but it has NO EFFECT here: encoding/json ignores omitempty on a uuid.UUID (a [16]byte array) and on a time.Time (a struct), so this key is ALWAYS present, at the zero value when unset.

date_start?string

RFC 3339 date-time. The column is a DATE, but the handler parses the value with time.Parse(time.RFC3339, ...) before decoding the rest of the body, so a bare "2026-08-27" is rejected 400 common.invalid_input with error "invalid date_start format" — send a full timestamp such as "2026-08-27T00:00:00Z". Responses carry a full RFC 3339 date-time for the same reason: models.FxTariffFeeRange declares no MarshalJSON, so time.Time marshals in full. The Go tag carries omitempty, but it has NO EFFECT here: encoding/json ignores omitempty on a uuid.UUID (a [16]byte array) and on a time.Time (a struct), so this key is ALWAYS present, at the zero value when unset.

date_end?string

RFC 3339 date-time. The column is a DATE, but the handler parses the value with time.Parse(time.RFC3339, ...) before decoding the rest of the body, so a bare "2026-08-27" is rejected 400 common.invalid_input with error "invalid date_end format" — send a full timestamp such as "2026-08-27T00:00:00Z". Responses carry a full RFC 3339 date-time for the same reason: models.FxTariffFeeRange declares no MarshalJSON, so time.Time marshals in full. The Go tag carries omitempty, but it has NO EFFECT here: encoding/json ignores omitempty on a uuid.UUID (a [16]byte array) and on a time.Time (a struct), so this key is ALWAYS present, at the zero value when unset.

active?boolean

Read by the handler even though it is not on FxTariffFeeInput; omitting it on update leaves the stored value alone.

Response Body

`application/json`

curl -X POST "https://example.com/v1/fx/tariffs/fees" \  -H "Content-Type: application/json" \  -d '{}'

{
  "min_range": 0,
  "max_range": 0,
  "fixed_fee": 0,
  "percent_fee": 0.01,
  "min_fee": 0,
  "max_fee": 0,
  "method": "fixed",
  "base_currency": "67615cab-16f6-4751-af40-c6c0dbcaffe0",
  "target_currency": "3b3e8109-66d3-4a6d-b9f1-d0865976f9f8",
  "fx_tariff_id": "f12d958c-c80c-4752-862c-9e0c09506488",
  "date_start": "2019-08-24T14:15:22Z",
  "date_end": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  "modified_at": "2019-08-24T14:15:22Z",
  "modified_by": "e8d4374d-93a1-4e98-a6c6-fdcf00c5059f",
  "active": true,
  "metadata": {}
}

{
  "status": 409,
  "message": "Spread rule overlaps an existing rule",
  "code": "fx_m.spread_overlap",
  "class": "business",
  "retryable": false,
  "details": [
    {
      "field": "percent_fee",
      "rule": "lte",
      "param": "1",
      "message": "string"
    }
  ]
}

{
  "status": 409,
  "message": "Spread rule overlaps an existing rule",
  "code": "fx_m.spread_overlap",
  "class": "business",
  "retryable": false,
  "details": [
    {
      "field": "percent_fee",
      "rule": "lte",
      "param": "1",
      "message": "string"
    }
  ]
}

{
  "status": 403,
  "message": "Access denied",
  "code": "common.forbidden",
  "class": "business"
}

{
  "status": 429,
  "message": "Rate limit for 203.0.113.7 to GET:/v1/fx/rates exceeded.",
  "code": "rate_limits_m.exceeded",
  "class": "temporary",
  "retryable": true
}

{
  "status": 409,
  "message": "Spread rule overlaps an existing rule",
  "code": "fx_m.spread_overlap",
  "class": "business",
  "retryable": false,
  "details": [
    {
      "field": "percent_fee",
      "rule": "lte",
      "param": "1",
      "message": "string"
    }
  ]
}

{
  "overall_status": "unhealthy",
  "message": "Service is shutting down",
  "timestamp": "2026-08-27T15:04:05Z"
}

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

429application/json

500application/json

503application/json

Graceful shutdown — LifecycleMiddleware, root router, not the envelope

ensureCacheAvailable could not reach the auth cache — the envelope

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`