Finance API

What customers owe and pay, and what the business spends.

Module code finance · 42 actions · 13 data models · 30 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: finance (everything), finance:read (read only) or finance:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

finance.accrue_commission

Accrue a commission — Opens what the affiliate is owed, at the rate frozen on the day of the agreement.

Needs finance:write · changes data

• Canonical address: POST /api/v1/actions/finance.accrue_commission

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.commission_accrued

What it writes: commission (insert) — Opens the commission

curl -X POST https://app.getera.io/api/v1/commissions/actions/accrue_commission \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"agreementId":"AGREEMENT_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.commission_accrued"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.commissions.accrueCommission({
  agreementId: "AGREEMENT_ID"
})

era commissions accrue_commission \
  --agreement-id "AGREEMENT_ID"

{
  "name": "era__finance__accrue_commission",
  "arguments": {
    "agreementId": "AGREEMENT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 agreement_not_found, commission_already_exists, agreement_has_no_affiliate, affiliate_not_active · 429 slow down

finance.allocate_payment

Allocate a collection — Spreads one collection across the instalments it paid off.

Needs finance:write · changes data

• Canonical address: POST /api/v1/actions/finance.allocate_payment

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.payment_allocated

What it writes: payment_allocation (insert) — Writes the allocations

curl -X POST https://app.getera.io/api/v1/payment_allocations/actions/allocate_payment \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"paymentId":"PAYMENT_ID","allocations":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.payment_allocated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.paymentAllocations.allocatePayment({
  paymentId: "PAYMENT_ID",
  allocations: {}
})

era payment_allocations allocate_payment --data '{"paymentId":"PAYMENT_ID","allocations":{}}'

{
  "name": "era__finance__allocate_payment",
  "arguments": {
    "paymentId": "PAYMENT_ID",
    "allocations": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 payment_not_found, no_allocations, unknown_allocation_target, invalid_allocation_amount, duplicate_allocation_target, allocation_exceeds_payment, allocation_target_not_found, allocation_currency_mismatch, allocation_customer_mismatch, allocation_exceeds_target · 429 slow down

finance.apply_discount

Apply a discount — Reduces an agreement, and freezes the reduced amount on the row.

Needs finance:write · changes data

• Canonical address: POST /api/v1/actions/finance.apply_discount

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.discount_applied

What it writes: discount_line (insert) — Writes the discount; agreement (update) — Freezes the discounted total

curl -X POST https://app.getera.io/api/v1/agreements/AGREEMENT_ID/actions/apply_discount \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"value":1,"reason":"Reason"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.discount_applied"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.agreements.applyDiscount("AGREEMENT_ID", {
  value: 1,
  reason: "Reason"
})

era agreements apply_discount AGREEMENT_ID \
  --value 1 \
  --reason "Reason"

{
  "name": "era__finance__apply_discount",
  "arguments": {
    "agreementId": "AGREEMENT_ID",
    "value": 1,
    "reason": "Reason"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 agreement_not_found, agreement_closed, discount_value_negative, discount_percentage_over_100, discount_after_collection, discount_over_cap, discount_actor_required · 429 slow down

finance.approve_expense

Approve an expense — Signs an expense off. Never your own.

Needs finance:approve · changes data

• Canonical address: POST /api/v1/actions/finance.approve_expense

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.expense_approved

What it writes: expense (update) — Stamps the approval

curl -X POST https://app.getera.io/api/v1/expenses/EXPENSE_ID/actions/approve_expense \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.expense_approved"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.expenses.approveExpense("EXPENSE_ID")

era expenses approve_expense EXPENSE_ID

{
  "name": "era__finance__approve_expense",
  "arguments": {
    "id": "EXPENSE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:approve · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 expense_not_found, expense_already_decided, cannot_approve_own_expense · 429 slow down

finance.approve_refund

Approve a refund — Approves a request and executes it: the money is recorded as gone back.

Needs finance:approve · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/finance.approve_refund

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.refund_approved, finance.payment_refunded

What it writes: payment_event (insert) — Records the refund step; payment (update) — Moves the pending and refunded amounts; payment_allocation (insert) — Writes the negative allocation; installment (update) — Reopens an instalment it no longer covers

curl -X POST https://app.getera.io/api/v1/payment_events/PAYMENT_EVENT_ID/actions/approve_refund \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.refund_approved",
    "finance.payment_refunded"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.paymentEvents.approveRefund("PAYMENT_EVENT_ID")

era payment_events approve_refund PAYMENT_EVENT_ID

{
  "name": "era__finance__approve_refund",
  "arguments": {
    "requestId": "PAYMENT_EVENT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:approve · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 refund_request_not_found, refund_request_resolved, refund_not_available, payment_app_not_connected, payment_credentials_invalid · 429 slow down

finance.cancel_agreement

Cancel an agreement — Closes the agreement and its pending instalments. Nothing is deleted.

Needs finance:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/finance.cancel_agreement

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.agreement_cancelled

What it writes: agreement (update) — Marks it cancelled; installment (update) — Cancels the pending instalments

curl -X POST https://app.getera.io/api/v1/agreements/AGREEMENT_ID/actions/cancel_agreement \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"Reason"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.agreement_cancelled"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.agreements.cancelAgreement("AGREEMENT_ID", {
  reason: "Reason"
})

era agreements cancel_agreement AGREEMENT_ID \
  --reason "Reason"

{
  "name": "era__finance__cancel_agreement",
  "arguments": {
    "id": "AGREEMENT_ID",
    "reason": "Reason"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 agreement_not_found, already_cancelled, agreement_has_collection · 429 slow down

finance.cancel_commission

Cancel a commission — Zeroes a commission that has not been paid. A paid one is never removed.

Needs finance:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/finance.cancel_commission

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.commission_cancelled

What it writes: commission (update) — Cancels it and zeroes the amount

curl -X POST https://app.getera.io/api/v1/commissions/COMMISSION_ID/actions/cancel_commission \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.commission_cancelled"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.commissions.cancelCommission("COMMISSION_ID")

era commissions cancel_commission COMMISSION_ID

{
  "name": "era__finance__cancel_commission",
  "arguments": {
    "id": "COMMISSION_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 commission_not_found, paid_commission_not_deletable · 429 slow down

finance.cancel_installment

Cancel an instalment — Takes an instalment out of the plan without deleting it.

Needs finance:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/finance.cancel_installment

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.installment_cancelled

What it writes: installment (update) — Marks it cancelled

curl -X POST https://app.getera.io/api/v1/installments/INSTALLMENT_ID/actions/cancel_installment \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.installment_cancelled"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.installments.cancelInstallment("INSTALLMENT_ID")

era installments cancel_installment INSTALLMENT_ID

{
  "name": "era__finance__cancel_installment",
  "arguments": {
    "id": "INSTALLMENT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 installment_not_found, installment_has_collection · 429 slow down

finance.cancel_payment

Release a payment — Cancels what is authorized and not charged.

Needs finance:write · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/finance.cancel_payment

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.payment_provider_event

What it writes: payment (update) — Moves the amounts and stores what the provider now allows; payment_event (insert) — Records the provider’s answer

curl -X POST https://app.getera.io/api/v1/payments/PAYMENT_ID/actions/cancel_payment \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"outcome":"success"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.payment_provider_event"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.payments.cancelPayment("PAYMENT_ID", {
  outcome: "success"
})

era payments cancel_payment PAYMENT_ID \
  --outcome "success"

{
  "name": "era__finance__cancel_payment",
  "arguments": {
    "paymentId": "PAYMENT_ID",
    "outcome": "success"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 payment_not_found, cancel_not_available, payment_app_not_connected, payment_credentials_invalid · 429 slow down

finance.capture_payment

Capture a payment — Charges money that was only authorized.

Needs finance:write · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/finance.capture_payment

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.payment_provider_event, finance.payment_recorded

What it writes: payment (update) — Moves the amounts and stores what the provider now allows; payment_event (insert) — Records the provider’s answer; payment_allocation (insert) — Puts charged money on the instalment; installment (update) — Closes the instalment once covered

curl -X POST https://app.getera.io/api/v1/payments/PAYMENT_ID/actions/capture_payment \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount":1}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.payment_provider_event",
    "finance.payment_recorded"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.payments.capturePayment("PAYMENT_ID", {
  amount: 1
})

era payments capture_payment PAYMENT_ID \
  --amount 1

{
  "name": "era__finance__capture_payment",
  "arguments": {
    "paymentId": "PAYMENT_ID",
    "amount": 1
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 payment_not_found, charge_not_available, capture_exceeds_authorized, payment_app_not_connected, payment_credentials_invalid · 429 slow down

finance.configure_payment_app

Configure a payment app — Enables, orders and selects test mode for a connected payment app.

Needs finance:manage · changes data

• Canonical address: POST /api/v1/actions/finance.configure_payment_app

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.payment_method_changed

What it writes: payment_provider_config (upsert) — Saves checkout enablement, order and test mode

curl -X POST https://app.getera.io/api/v1/payment_provider_configs/actions/configure_payment_app \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"provider":"Provider","credentialId":"CREDENTIAL_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.payment_method_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.paymentProviderConfigs.configurePaymentApp({
  provider: "Provider",
  credentialId: "CREDENTIAL_ID"
})

era payment_provider_configs configure_payment_app \
  --provider "Provider" \
  --credential-id "CREDENTIAL_ID"

{
  "name": "era__finance__configure_payment_app",
  "arguments": {
    "provider": "Provider",
    "credentialId": "CREDENTIAL_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 unsupported_payment_app, payment_credential_mismatch, payment_app_unavailable · 429 slow down

finance.create_agreement

Open an agreement — Records what somebody owes, in the workspace currency unless told otherwise.

Needs finance:write · changes data

• REST alias: POST /api/v1/agreements
• Canonical address: POST /api/v1/actions/finance.create_agreement

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.agreement_created

What it writes: agreement (insert) — Opens the agreement; agreement_line (insert) — Writes its lines

curl -X POST https://app.getera.io/api/v1/agreements/actions/create_agreement \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"customerId":"CUSTOMER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.agreement_created"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.agreements.create({
  customerId: "CUSTOMER_ID"
})

era agreements create \
  --customer-id "CUSTOMER_ID"

{
  "name": "era__finance__create_agreement",
  "arguments": {
    "customerId": "CUSTOMER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 customer_not_found, customer_archived, invalid_currency, affiliate_not_active, agreement_total_not_positive · 429 slow down

finance.create_expense

Record an expense — Money going out, against a category, awaiting approval.

Needs finance:write · changes data

• REST alias: POST /api/v1/expenses
• Canonical address: POST /api/v1/actions/finance.create_expense

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.expense_created

What it writes: expense (insert) — Records the expense

curl -X POST https://app.getera.io/api/v1/expenses/actions/create_expense \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"categoryId":"EXPENSE_CATEGORY_ID","title":"What it was","amount":1,"expenseDate":"2026-11-02"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.expense_created"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.expenses.create({
  categoryId: "EXPENSE_CATEGORY_ID",
  title: "What it was",
  amount: 1,
  expenseDate: "2026-11-02"
})

era expenses create \
  --category-id "EXPENSE_CATEGORY_ID" \
  --title "What it was" \
  --amount 1 \
  --expense-date "2026-11-02"

{
  "name": "era__finance__create_expense",
  "arguments": {
    "categoryId": "EXPENSE_CATEGORY_ID",
    "title": "What it was",
    "amount": 1,
    "expenseDate": "2026-11-02"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 expense_category_not_available, invalid_currency, expense_amount_negative, expense_amount_over_cap, expense_date_in_future, expense_recurring_period_required · 429 slow down

finance.deactivate_expense_category

Deactivate an expense category — Stops new expenses landing on it. Existing ones keep theirs.

Needs finance:manage · changes data

• Canonical address: POST /api/v1/actions/finance.deactivate_expense_category

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.expense_category_changed

What it writes: expense_category (update) — Clears is_active

curl -X POST https://app.getera.io/api/v1/expense_categories/EXPENSE_CATEGORY_ID/actions/deactivate_expense_category \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.expense_category_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.expenseCategories.deactivateExpenseCategory("EXPENSE_CATEGORY_ID")

era expense_categories deactivate_expense_category EXPENSE_CATEGORY_ID

{
  "name": "era__finance__deactivate_expense_category",
  "arguments": {
    "id": "EXPENSE_CATEGORY_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 expense_category_not_found · 429 slow down

finance.mark_expense_paid

Mark an expense paid — Stamps the day the money left. The date is what "paid" means here.

Needs finance:write · changes data

• Canonical address: POST /api/v1/actions/finance.mark_expense_paid

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.expense_paid

What it writes: expense (update) — Stamps the payment date

curl -X POST https://app.getera.io/api/v1/expenses/EXPENSE_ID/actions/mark_expense_paid \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"paymentDate":"2026-11-02"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.expense_paid"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.expenses.markExpensePaid("EXPENSE_ID", {
  paymentDate: "2026-11-02"
})

era expenses mark_expense_paid EXPENSE_ID \
  --payment-date "2026-11-02"

{
  "name": "era__finance__mark_expense_paid",
  "arguments": {
    "id": "EXPENSE_ID",
    "paymentDate": "2026-11-02"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 expense_not_found, expense_not_approved, expense_paid_without_date · 429 slow down

finance.open_draft_for_source

Draft an agreement for a record — Machine-only: the agreement a won lead, a booking, a package, an order or a subscription period implies.

Needs finance:write · changes data

• Canonical address: POST /api/v1/actions/finance.open_draft_for_source

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.agreement_created, finance.payment_recorded

What it writes: agreement (insert) — Drafts the agreement; agreement (update) — Totals the discounts it came with; agreement_line (insert) — Writes what was sold, with its frozen tax, when the source says; discount_line (insert) — Writes the promotions and coupons the source applied; payment (insert) — Records what gift cards already paid, as collections; payment_event (insert) — The gift card charge; payment_allocation (insert) — Allocates it to the agreement

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 agreement_exists_for_source, customer_not_found, customer_archived, invalid_currency, payment_amount_not_positive, allocation_exceeds_target · 429 slow down

finance.pay_site_agreement

Pay by link (site) — A visitor pays what a booking deposit, ticket, package or open instalment still owes, by its payment link, through a connected payment app or the test method.

Needs finance:write · reaches outside (sends, publishes or charges) · Also callable from a published site (visitor)

• Canonical address: POST /api/v1/actions/finance.pay_site_agreement

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.payment_provider_event, finance.payment_recorded, finance.installments_scheduled

What it writes: installment (insert) — The whole agreement as one instalment due today, when it has none; payment (insert) — Opens the transaction; payment_event (insert) — Records the provider’s answer; payment_allocation (insert) — Puts what was charged, and what a gift card paid, on the instalment; installment (update) — Closes the instalment when card and method cover it

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 pay_link_invalid, payment_method_unavailable, gift_card_hold_expired, nothing_due · 429 slow down

finance.pay_site_order

Pay for an order (site) — A visitor pays what their website order still owes, through a connected payment app or the test method.

Needs finance:write · reaches outside (sends, publishes or charges) · Also callable from a published site (visitor)

• Canonical address: POST /api/v1/actions/finance.pay_site_order

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.payment_provider_event, finance.payment_recorded, finance.installments_scheduled

What it writes: installment (insert) — The whole order as one instalment due today, when it has none; payment (insert) — Opens the transaction; payment_event (insert) — Records the provider’s answer; payment_allocation (insert) — Puts what was charged, and what a gift card paid, on the instalment; installment (update) — Closes the instalment when card and method cover it

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 order_not_found, payment_method_unavailable, gift_card_hold_expired, payment_not_ready · 429 slow down

finance.raise_installment_notices

Raise instalment reminders — Machine-only (the daily finance routine): flags every pending instalment falling due within the reminder window, and every one past due, once each.

Needs finance:write · changes data

• Canonical address: POST /api/v1/actions/finance.raise_installment_notices

Input

Events it publishes: finance.installment_due, finance.installment_overdue

What it writes: installment (update) — Records that the customer was told (due soon / overdue)

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 429 slow down

finance.recalculate_commission

Recalculate the commission — K-09: brings a pending commission in line with what has been collected (calculate_commission_amount_v3). Runs on every collection and refund; the button runs it by hand.

Needs finance:write · changes data

• Canonical address: POST /api/v1/actions/finance.recalculate_commission

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.commission_recalculated

What it writes: commission (update) — Writes the amount the collections support

curl -X POST https://app.getera.io/api/v1/commissions/actions/recalculate_commission \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"agreementId":"AGREEMENT_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.commission_recalculated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.commissions.recalculateCommission({
  agreementId: "AGREEMENT_ID"
})

era commissions recalculate_commission \
  --agreement-id "AGREEMENT_ID"

{
  "name": "era__finance__recalculate_commission",
  "arguments": {
    "agreementId": "AGREEMENT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 commission_not_found · 429 slow down

finance.record_commission_payout

Record a commission payout — One transfer to an affiliate that pays a set of pending commissions.

Needs finance:approve · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/finance.record_commission_payout

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.commission_payout_recorded, finance.commission_status_changed

What it writes: commission_payout (insert) — Records the transfer; commission (update) — Marks the commissions paid by it

curl -X POST https://app.getera.io/api/v1/commission_payouts/actions/record_commission_payout \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"affiliateId":"AFFILIATE_ID","commissionIds":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.commission_payout_recorded",
    "finance.commission_status_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.commissionPayouts.recordCommissionPayout({
  affiliateId: "AFFILIATE_ID",
  commissionIds: {}
})

era commission_payouts record_commission_payout --data '{"affiliateId":"AFFILIATE_ID","commissionIds":{}}'

{
  "name": "era__finance__record_commission_payout",
  "arguments": {
    "affiliateId": "AFFILIATE_ID",
    "commissionIds": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:approve · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 no_commissions_selected, affiliate_not_found, commission_not_payable · 429 slow down

finance.record_gift_card_payment

Record a gift card collection — Machine-only (gift_cards.redeemed): the part of a sale a gift card paid, as a collection against its agreement.

Needs finance:write · changes data

• Canonical address: POST /api/v1/actions/finance.record_gift_card_payment

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.payment_recorded

What it writes: payment (insert) — The gift card collection; payment_event (insert) — Its charge; payment_allocation (insert) — Allocated to the agreement

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 no_agreement_for_source, allocation_currency_mismatch, payment_amount_not_positive, allocation_exceeds_target · 429 slow down

finance.record_payment

Record a collection — Money arrived: writes the movement, the event and what it paid off.

Needs finance:write · changes data

• Canonical address: POST /api/v1/actions/finance.record_payment

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.payment_recorded

What it writes: payment (insert) — Records the movement; payment_event (insert) — Records the charge event; payment_allocation (insert) — Says what it paid off; installment (update) — Closes the instalment when it is covered

curl -X POST https://app.getera.io/api/v1/installments/INSTALLMENT_ID/actions/record_payment \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount":1}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.payment_recorded"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.installments.recordPayment("INSTALLMENT_ID", {
  amount: 1
})

era installments record_payment INSTALLMENT_ID \
  --amount 1

{
  "name": "era__finance__record_payment",
  "arguments": {
    "installmentId": "INSTALLMENT_ID",
    "amount": 1
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 installment_not_found, installment_cancelled, payment_amount_not_positive, duplicate_payment_idempotency_key, overpayment · 429 slow down

finance.record_provider_webhook

Record a payment webhook — Admits one verified provider event once and applies it to the canonical payment.

Needs finance:write · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/finance.record_provider_webhook

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.payment_provider_event, finance.payment_recorded

What it writes: finance_provider_event (insert) — Admits the external event once; payment (update) — Moves the amounts and stores what the provider now allows; payment_event (insert) — Records the provider’s answer; payment_allocation (insert) — Puts charged money on the instalment; installment (update) — Closes the instalment once covered

curl -X POST https://app.getera.io/api/v1/payments/PAYMENT_ID/actions/record_provider_webhook \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"provider":"Provider","externalId":"Provider event","type":"Event type","amount":1,"currency":"Currency","occurredAt":"2026-11-02T09:00:00Z"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.payment_provider_event",
    "finance.payment_recorded"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.payments.recordProviderWebhook("PAYMENT_ID", {
  provider: "Provider",
  externalId: "Provider event",
  type: "Event type",
  amount: 1,
  currency: "Currency",
  occurredAt: "2026-11-02T09:00:00Z"
})

era payments record_provider_webhook PAYMENT_ID \
  --provider "Provider" \
  --external-id "Provider event" \
  --type "Event type" \
  --amount 1 \
  --currency "Currency" \
  --occurred-at "2026-11-02T09:00:00Z"

{
  "name": "era__finance__record_provider_webhook",
  "arguments": {
    "paymentId": "PAYMENT_ID",
    "provider": "Provider",
    "externalId": "Provider event",
    "type": "Event type",
    "amount": 1,
    "currency": "Currency",
    "occurredAt": "2026-11-02T09:00:00Z"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 unknown_payment_provider, webhook_payment_not_found, webhook_provider_mismatch · 429 slow down

finance.record_source_discounts

Record the shop’s discounts — Machine-only (retail.order_discounts_applied): mirrors the promotions and coupons on an order as discount lines on its agreement.

Needs finance:write · removes or cannot be undone

• Canonical address: POST /api/v1/actions/finance.record_source_discounts

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: discount_line (delete) — Drops what the shop wrote before; discount_line (insert) — Writes the current set; agreement (update) — Totals the discounts

Errors: 401 no or expired credential · 403 the credential does not hold finance:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 no_agreement_for_source · 429 slow down

finance.refund_payment

Refund a collection — Sends money back. A refund is an event on the collection, not a record of its own.

Needs finance:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/finance.refund_payment

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.payment_refunded

What it writes: payment_event (insert) — Records the refund event; payment (update) — Raises the refunded amount; payment_allocation (insert) — Writes the negative allocation; installment (update) — Reopens an instalment it no longer covers

curl -X POST https://app.getera.io/api/v1/payments/PAYMENT_ID/actions/refund_payment \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount":1,"reason":"Reason"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.payment_refunded"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.payments.refundPayment("PAYMENT_ID", {
  amount: 1,
  reason: "Reason"
})

era payments refund_payment PAYMENT_ID \
  --amount 1 \
  --reason "Reason"

{
  "name": "era__finance__refund_payment",
  "arguments": {
    "paymentId": "PAYMENT_ID",
    "amount": 1,
    "reason": "Reason"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 payment_not_found, refund_not_available, payment_app_not_connected, payment_credentials_invalid, refund_exceeds_charged · 429 slow down

finance.reject_expense

Reject an expense — Turns an expense down, with the reason the source never required.

Needs finance:approve · changes data

• Canonical address: POST /api/v1/actions/finance.reject_expense

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.expense_rejected

What it writes: expense (update) — Records the rejection

curl -X POST https://app.getera.io/api/v1/expenses/EXPENSE_ID/actions/reject_expense \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"Reason"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.expense_rejected"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.expenses.rejectExpense("EXPENSE_ID", {
  reason: "Reason"
})

era expenses reject_expense EXPENSE_ID \
  --reason "Reason"

{
  "name": "era__finance__reject_expense",
  "arguments": {
    "id": "EXPENSE_ID",
    "reason": "Reason"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:approve · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 expense_not_found, expense_already_decided, expense_rejection_reason_required · 429 slow down

finance.reject_refund

Reject a refund — Turns a request down, with the reason on the collection’s trail.

Needs finance:approve · removes or cannot be undone

• Canonical address: POST /api/v1/actions/finance.reject_refund

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.refund_rejected

What it writes: payment_event (insert) — Records the refund step; payment (update) — Moves the pending and refunded amounts

curl -X POST https://app.getera.io/api/v1/payment_events/PAYMENT_EVENT_ID/actions/reject_refund \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"Reason"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.refund_rejected"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.paymentEvents.rejectRefund("PAYMENT_EVENT_ID", {
  reason: "Reason"
})

era payment_events reject_refund PAYMENT_EVENT_ID \
  --reason "Reason"

{
  "name": "era__finance__reject_refund",
  "arguments": {
    "requestId": "PAYMENT_EVENT_ID",
    "reason": "Reason"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:approve · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 refund_request_not_found, refund_request_resolved · 429 slow down

finance.remove_discount

Remove a discount — Takes a discount off and puts the amount back on the agreement.

Needs finance:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/finance.remove_discount

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: finance.discount_removed

What it writes: discount_line (delete) — Removes the discount; agreement (update) — Restores the total

curl -X POST https://app.getera.io/api/v1/discount_lines/DISCOUNT_LINE_ID/actions/remove_discount \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "finance.discount_removed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.discountLines.removeDiscount("DISCOUNT_LINE_ID")

era discount_lines remove_discount DISCOUNT_LINE_ID

{
  "name": "era__finance__remove_discount",
  "arguments": {
    "id": "DISCOUNT_LINE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold finance:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 discount_not_found, agreement_not_found, agreement_closed · 429 slow down

finance.request_refund