# Margin & Markup API
> Pricing and profitability maths as an API. The margin endpoint solves the relationships between unit cost, selling price, gross margin (a percentage of the price), markup (a percentage of the cost) and profit — give it any two of these and it works out all the rest. Price a product from a target margin, find the true margin of an existing price, convert a markup into a margin (they are not the same — the same price always has a lower margin than markup), or back out a cost from a price and markup. The breakeven endpoint computes how many units, and how much revenue, you need to sell to cover your fixed costs, given a unit price and a variable cost per unit, and returns the contribution margin and contribution-margin ratio. Negative results are reported honestly so a loss-making price is obvious. Everything is computed locally and deterministically, so it is instant and private. Ideal for e-commerce and retail pricing, quoting and sales tooling, finance and FP&A, marketplaces and POS systems, and unit-economics modelling. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is pricing maths; for everyday percentage operations use a percentage API and for loan and interest maths use a finance-calculator API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/margin-api/..."
```

## Pricing
- **Free** (Free) — 3,335 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 12,850 calls/Mo, 8 req/s
- **Pro** ($25/Mo) — 179,500 calls/Mo, 20 req/s
- **Mega** ($63/Mo) — 940,000 calls/Mo, 50 req/s

## Endpoints

### Margin

#### `GET /v1/breakeven` — Break-even analysis

**Parameters:**
- `fixed_costs` (query, required, string) — Total fixed costs Example: `10000`
- `price` (query, required, string) — Selling price per unit Example: `25`
- `variable_cost` (query, optional, string) — Variable cost per unit (default 0) Example: `15`
- `round` (query, optional, string) — Decimal places (default 2)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/margin-api/v1/breakeven?fixed_costs=10000&price=25&variable_cost=15"
```

**Response:**
```json
{
    "data": {
        "price": 25,
        "fixed_costs": 10000,
        "variable_cost": 15,
        "break_even_units": 1000,
        "break_even_revenue": 25000,
        "contribution_margin": 10,
        "contribution_margin_ratio": 40,
        "break_even_units_rounded_up": 1000
    },
    "meta": {
        "timestamp": "2026-06-03T09:25:00.902Z",
        "request_id": "ddc2e46d-214e-4e34-a043-62e492e793ae"
    },
    "status": "ok",
    "message": "Break-even analysis",
    "success": true
}
```

#### `GET /v1/margin` — Solve pricing maths

**Parameters:**
- `cost` (query, optional, string) — Unit cost Example: `60`
- `price` (query, optional, string) — Selling price Example: `100`
- `profit` (query, optional, string) — Profit per unit
- `margin` (query, optional, string) — Gross margin % (of price)
- `markup` (query, optional, string) — Markup % (of cost)
- `round` (query, optional, string) — Decimal places (default 2)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/margin-api/v1/margin?cost=60&price=100"
```

**Response:**
```json
{
    "data": {
        "cost": 60,
        "price": 100,
        "profit": 40,
        "profitable": true,
        "margin_percent": 40,
        "markup_percent": 66.67
    },
    "meta": {
        "timestamp": "2026-06-03T09:25:01.018Z",
        "request_id": "c118fc13-c7e7-445e-ad48-45077c10416f"
    },
    "status": "ok",
    "message": "Solve pricing maths",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/margin-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "name": "Margin & Markup API",
        "notes": "Margin is profit ÷ price; markup is profit ÷ cost — the same price has a lower margin than markup. Two percentages alone (margin + markup) cannot give absolute amounts; include a cost, price or profit. This is pricing maths — for everyday percentage operations use a percentage API. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/margin",
                "params": {
                    "cost": "unit cost",
                    "price": "selling price",
                    "round": "decimal places (default 2)",
                    "margin": "gross margin % (of price)",
                    "markup": "markup % (of cost)",
                    "profit": "profit per unit"
                },
                "returns": "cost, price, profit, margin % and markup %"
            },
            {
                "path": "/v1/breakeven",
                "params": {
                    "price": "selling price per unit (required)",
                    "round": "decimal places (default 2)",
                    "fixed_costs": "total fixed costs (required)",
                    "variable_cost": "variable cost per unit (default 0)"
                },
                "returns": "break-even units, revenue and contribution margin"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this doc
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/margin-api
OpenAPI spec: https://www.oanor.com/api/margin-api/openapi.json