Enrichment API | Lune Docs

Endpoint

POST /v1/enrich

Request body

Field	Type	Required	Description
`description`	string	yes	Raw transaction descriptor as it appears on the statement. Max 256 chars.
`amount`	number	yes	Transaction amount in the original currency. Signed: negative for refunds.
`currency`	string	yes	ISO 4217 three-letter currency code, uppercase.
`timestamp`	string	no	ISO-8601 timestamp. Improves recurring detection accuracy.
`account_id`	string	no	Stable account identifier; enables cross-transaction patterns.
`country`	string	no	ISO 3166 country hint for the merchant graph lookup.

Example

curl https://api.lunedata.io/v1/enrich \
  -H "Authorization: Bearer lune_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "description": "AMZN MKTP US*A1B2C3 AMZN.COM/BILL",
    "amount": 42.99,
    "currency": "USD",
    "timestamp": "2026-05-23T10:14:00Z",
    "country": "US"
  }'

result = lune.enrich(
    description="AMZN MKTP US*A1B2C3 AMZN.COM/BILL",
    amount=42.99,
    currency="USD",
    timestamp="2026-05-23T10:14:00Z",
    country="US",
)
print(result.merchant.name, result.category)

const result = await lune.enrich({
  description: 'AMZN MKTP US*A1B2C3 AMZN.COM/BILL',
  amount: 42.99,
  currency: 'USD',
  timestamp: '2026-05-23T10:14:00Z',
  country: 'US',
});
console.log(result.merchant.name, result.category);

result, err := lune.Enrich(ctx, &lune.EnrichRequest{
    Description: "AMZN MKTP US*A1B2C3 AMZN.COM/BILL",
    Amount:      42.99,
    Currency:    "USD",
    Timestamp:   "2026-05-23T10:14:00Z",
    Country:     "US",
})
if err != nil { return err }
fmt.Println(result.Merchant.Name, result.Category)

Response fields

{
  "merchant": {
    "id": "mer_amzn_us",
    "name": "Amazon",
    "logo": "https://cdn.lunedata.io/m/amazon.svg",
    "location": null,
    "website": "https://amazon.com"
  },
  "category": "shopping.marketplace",
  "category_path": ["shopping", "marketplace"],
  "carbon_g": 312,
  "recurring": {
    "is_recurring": false,
    "confidence": 0.04
  },
  "confidence": 0.98,
  "latency_ms": 0.4
}

Category taxonomy

The taxonomy has three levels: group.category.subcategory. Returned codes are always in dot notation. Full mapping is available via GET /v1/enrich/categories. Top-level groups:

food — restaurants, coffee, groceries, delivery, alcohol.
shopping — marketplaces, clothing, electronics, home, books.
transport — fuel, ride-share, public transit, flights, parking.
bills — utilities, telecom, rent, mortgage, insurance.
entertainment — streaming, gaming, events, fitness.
finance — transfers, ATM, fees, interest.
income — salary, refunds, dividends, gifts.

Errors

Status	Body	Meaning
`400`	`invalid_field`	One or more fields failed validation. Body includes which.
`413`	`description_too_long`	Description exceeded 256 characters.
`422`	`unknown_currency`	Currency code isn't a recognized ISO 4217 value.
`429`	`rate_limited`	You exceeded your per-second quota. Retry-After header included.

Previous ← Authentication Next PFM SDK (Engage) →