Skip to main content

Margin Configuration

Margins define additional spread applied to exchange rates (quote). They directly affect the rate and totalAmount values returned by the quote endpoint.


Overview​

A margin is a cost adjustment applied on top of the base exchange rate. When a quote is generated, any configured margins for the matching context and currency are automatically applied.

Endpoint​

PUT /margin

API Reference: Create or update margin settings


Authentication​

This endpoint requires a valid x-api-key and a Bearer Token in the Authorization issued to a store or branch role in headers:

x-api-key: <your_api_key>
Authorization: Bearer <access_token>

supervisor user requests will be rejected

See the Authentication Guide to see more details.

The following user roles are authorized to use this endpoint:

RoleCapabilities
storeCreate global and individual margins
branchManage margins scoped to their own data

Margin Types​

The type field determines how the margin value is applied to the base rate:

TypeDescription
fixedAdds a fixed absolute amount to the operation
percentageApplies a percentage over the base exchange rate

Margin Scope​

Margins can be scoped globally or to a specific branch:

Global​

  • Can be created by both store and branch users.
  • When created by a store:
    • The margin applies to the store itself.
    • It is automatically propagated to all its branches.
  • When created by a branch:
    • The margin applies only to that specific branch. ownerId must NOT be included in the request body.

Individual​

  • Can only be created from store user into a branch user via ownerId
  • ownerId represents the branch identifier (branch.id)

Request Example​

curl -X PUT "/api/v1/margin" \
-H "Content-Type: application/json" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <your_access_token>" \
-d '{
"type": "percentage",
"context": "payment_order",
"value": 2.5,
"currency": "BRL",
"ownerId": "123e4567-e89b-12d3-a456-426614174010"
}'

In this example, a 2.5% margin is applied to payment_order operations in BRL, scoped to the branch identified by ownerId.

Owner id is the id of the branch entity (branch.id)


Example: How Margins Affect a Quote

Base values​

  • Base quote: 5.00
  • Global store margin: 0.01

1. Store global margin only​

When only the store-level global margin is applied, it affects the store itself and all of its branches. Every branch inherits this margin by default:

5.00 + 0.01 = 5.01

2. Individual branch margin + global store margin​

If a branch has its own fixed margin created by it store, it overrides the global store margin:

  • Individual branch margin created by store: 0.02
5.00 + 0.02 = 5.02

3. Branch with individual store margin + branch global margin​

If the branch has:

  • Store individual margin: 0.01
  • Branch global margin: 0.02

Then both are applied together:

5.00 + 0.01 + 0.02 = 5.03

4. Branch with both store margin + branch global margin​

If the branch has:

  • Store global margin: 0.01
  • Branch global margin: 0.02

Then both are applied together:

5.00 + 0.01 + 0.02 = 5.03

Important Notes​

  • store users can create both global and individual margins
  • branch users can only manage margins scoped to their own branch
  • Margins directly affect financial operations — review them carefully before going live