Umbra ERP

Finance & Accounting

Handle bills, payments, journal entries, and financial reporting. Track accounts payable, record payments, and maintain your general ledger.

GET/v1/finance/bills

List bills

Retrieve a paginated list of all bills (accounts payable).

Optional parameters

  • Name
    status
    Type
    string
    Description

    Filter by status: draft, pending, paid, overdue.

  • Name
    vendor_id
    Type
    string
    Description

    Filter by vendor/supplier ID.

  • Name
    limit
    Type
    integer
    Description

    Maximum number of records to return.

Request

GET
/v1/finance/bills
curl https://api.umbraerp.com/v1/finance/bills \
  -H "Authorization: Bearer <your_access_token>"

Response

{
  "result": "success",
  "bills": [
    {
      "id": "bill_001",
      "vendor_id": "vendor_abc",
      "amount": 50000,
      "currency": "USD",
      "status": "pending",
      "due_date": "2026-03-15",
      "created_at": "2026-02-15T10:30:00Z"
    }
  ]
}
POST/v1/finance/bills

Create bill

Create a new bill (accounts payable entry).

Required attributes

  • Name
    vendor_id
    Type
    string
    Description

    The vendor/supplier this bill is from.

  • Name
    items
    Type
    array
    Description

    Array of line items, each with description, quantity, and unit_price.

  • Name
    currency
    Type
    string
    Description

    Three-letter ISO currency code.

  • Name
    due_date
    Type
    string
    Description

    Payment due date (YYYY-MM-DD).

Request

POST
/v1/finance/bills
curl -X POST https://api.umbraerp.com/v1/finance/bills \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "vendor_abc",
    "items": [
      {
        "description": "Office Supplies",
        "quantity": 1,
        "unit_price": 50000
      }
    ],
    "currency": "USD",
    "due_date": "2026-03-15"
  }'

Response

{
  "result": "success",
  "bill_id": "bill_001",
  "message": "Bill created successfully."
}
GET/v1/finance/bills/:id

Get bill

Retrieve details of a specific bill.

Request

GET
/v1/finance/bills/bill_001
curl https://api.umbraerp.com/v1/finance/bills/bill_001 \
  -H "Authorization: Bearer <your_access_token>"
POST/v1/finance/bills/:id/pay

Record payment

Record a payment against a bill.

Required attributes

  • Name
    amount
    Type
    integer
    Description

    Payment amount in the smallest currency unit.

  • Name
    payment_method
    Type
    string
    Description

    Payment method: bank_transfer, cash, check, mobile_money.

  • Name
    payment_date
    Type
    string
    Description

    Date of payment (YYYY-MM-DD).

Request

POST
/v1/finance/bills/bill_001/pay
curl -X POST https://api.umbraerp.com/v1/finance/bills/bill_001/pay \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "payment_method": "bank_transfer",
    "payment_date": "2026-03-10"
  }'

Response

{
  "result": "success",
  "message": "Payment recorded successfully.",
  "bill_status": "paid"
}
GET/v1/finance/journal

List journal entries

Retrieve journal entries for the general ledger.

Optional parameters

  • Name
    start_date
    Type
    string
    Description

    Filter by start date (YYYY-MM-DD).

  • Name
    end_date
    Type
    string
    Description

    Filter by end date (YYYY-MM-DD).

  • Name
    account
    Type
    string
    Description

    Filter by account code.

Request

GET
/v1/finance/journal
curl https://api.umbraerp.com/v1/finance/journal \
  -H "Authorization: Bearer <your_access_token>"

Response

{
  "result": "success",
  "entries": [
    {
      "id": "je_001",
      "date": "2026-03-10",
      "description": "Payment for Office Supplies",
      "debits": [{"account": "5000", "amount": 50000}],
      "credits": [{"account": "1000", "amount": 50000}],
      "created_at": "2026-03-10T14:00:00Z"
    }
  ]
}
GET/v1/get/salesSchedule

Sales Schedule

Retrieve a sales schedule report showing invoiced revenue grouped by time period. Includes per-invoice detail, grouped subtotals with cumulative running totals, a summary, and the current VAT threshold status for your business.

Required parameters

  • Name
    startDate
    Type
    string
    Description

    Start date for the report period (YYYY-MM-DD).

  • Name
    endDate
    Type
    string
    Description

    End date for the report period (YYYY-MM-DD).

Optional parameters

  • Name
    groupBy
    Type
    string
    Description

    Grouping interval: month, quarter, or year. Defaults to month.

  • Name
    currency
    Type
    string
    Description

    Filter by three-letter ISO currency code.

Request

GET
/v1/get/salesSchedule
curl "https://api.umbraerp.com/v1/get/salesSchedule?startDate=2026-01-01&endDate=2026-03-31&groupBy=month" \
  -H "Authorization: Bearer <your_access_token>"

Response

{
  "result": "success",
  "data": {
    "items": [
      {
        "invoiceId": "inv_abc123",
        "invoiceNumber": "INV-0042",
        "clientName": "Acme Corp",
        "issueDate": "2026-01-15",
        "amount": 150000,
        "currency": "USD",
        "status": "paid"
      }
    ],
    "periods": [
      {
        "period": "2026-01",
        "label": "January 2026",
        "revenue": 150000,
        "invoiceCount": 1,
        "cumulative": 150000
      },
      {
        "period": "2026-02",
        "label": "February 2026",
        "revenue": 220000,
        "invoiceCount": 3,
        "cumulative": 370000
      }
    ],
    "summary": {
      "totalRevenue": 370000,
      "totalInvoices": 4,
      "currency": "USD"
    },
    "vatThreshold": {
      "configured": true,
      "thresholdAmount": 5000000,
      "currentRevenue": 370000,
      "percentageReached": 7.4,
      "registered": false
    }
  }
}
GET/v1/get/vatThreshold

VAT Threshold Config

Retrieve the VAT threshold configuration for the authenticated business. Returns the threshold amount, alert settings, and registration status. Returns null for data if no threshold has been configured.

Request

GET
/v1/get/vatThreshold
curl https://api.umbraerp.com/v1/get/vatThreshold \
  -H "Authorization: Bearer <your_access_token>"

Response

{
  "result": "success",
  "data": {
    "publicId": "vat_th_abc123",
    "country": "ZW",
    "thresholdAmount": 5000000,
    "currency": "USD",
    "periodType": "annual",
    "alertAtPercentage": 80,
    "alertEmail": "finance@example.com",
    "registered": false,
    "registrationDate": null,
    "registrationNumber": null,
    "createdAt": "2026-01-10T08:00:00Z",
    "updatedAt": "2026-01-10T08:00:00Z"
  }
}
POST/v1/create/vatThreshold

Create VAT Threshold

Create a VAT threshold configuration for your business. This sets the revenue threshold at which VAT registration becomes mandatory, and configures alert notifications.

Required attributes

  • Name
    country
    Type
    string
    Description

    Two-letter ISO country code for the jurisdiction.

  • Name
    thresholdAmount
    Type
    integer
    Description

    VAT registration threshold amount in the smallest currency unit (cents).

  • Name
    currency
    Type
    string
    Description

    Three-letter ISO currency code.

  • Name
    periodType
    Type
    string
    Description

    Threshold period: annual, quarterly, or rolling_12_months.

  • Name
    alertAtPercentage
    Type
    integer
    Description

    Percentage of threshold at which to send an alert (e.g., 80 for 80%).

  • Name
    alertEmail
    Type
    string
    Description

    Email address to receive threshold alerts.

Request

POST
/v1/create/vatThreshold
curl -X POST https://api.umbraerp.com/v1/create/vatThreshold \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "ZW",
    "thresholdAmount": 5000000,
    "currency": "USD",
    "periodType": "annual",
    "alertAtPercentage": 80,
    "alertEmail": "finance@example.com"
  }'

Response

{
  "result": "success",
  "data": {
    "publicId": "vat_th_abc123",
    "country": "ZW",
    "thresholdAmount": 5000000,
    "currency": "USD",
    "periodType": "annual",
    "alertAtPercentage": 80,
    "alertEmail": "finance@example.com",
    "registered": false,
    "registrationDate": null,
    "registrationNumber": null,
    "createdAt": "2026-01-10T08:00:00Z",
    "updatedAt": "2026-01-10T08:00:00Z"
  }
}
PUT/v1/update/vatThreshold/:publicId

Update VAT Threshold

Update an existing VAT threshold configuration. You can modify any of the configurable fields.

Optional attributes

  • Name
    thresholdAmount
    Type
    integer
    Description

    Updated threshold amount in the smallest currency unit (cents).

  • Name
    periodType
    Type
    string
    Description

    Updated threshold period: annual, quarterly, or rolling_12_months.

  • Name
    alertAtPercentage
    Type
    integer
    Description

    Updated alert percentage (e.g., 90 for 90%).

  • Name
    alertEmail
    Type
    string
    Description

    Updated email address for threshold alerts.

  • Name
    currency
    Type
    string
    Description

    Updated three-letter ISO currency code.

  • Name
    country
    Type
    string
    Description

    Updated two-letter ISO country code.

Request

PUT
/v1/update/vatThreshold/vat_th_abc123
curl -X PUT https://api.umbraerp.com/v1/update/vatThreshold/vat_th_abc123 \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "thresholdAmount": 7500000,
    "alertAtPercentage": 90
  }'

Response

{
  "result": "success",
  "data": {
    "publicId": "vat_th_abc123",
    "country": "ZW",
    "thresholdAmount": 7500000,
    "currency": "USD",
    "periodType": "annual",
    "alertAtPercentage": 90,
    "alertEmail": "finance@example.com",
    "registered": false,
    "registrationDate": null,
    "registrationNumber": null,
    "createdAt": "2026-01-10T08:00:00Z",
    "updatedAt": "2026-03-07T12:00:00Z"
  }
}
POST/v1/update/vatThreshold/:publicId/markRegistered

Mark VAT Registered

Mark a business as VAT registered. This records the registration date and number against the VAT threshold configuration, and updates the registration status.

Required attributes

  • Name
    registrationDate
    Type
    string
    Description

    Date of VAT registration (YYYY-MM-DD).

  • Name
    registrationNumber
    Type
    string
    Description

    Official VAT registration number issued by the tax authority.

Request

POST
/v1/update/vatThreshold/vat_th_abc123/markRegistered
curl -X POST https://api.umbraerp.com/v1/update/vatThreshold/vat_th_abc123/markRegistered \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "registrationDate": "2026-03-01",
    "registrationNumber": "VAT-2026-001234"
  }'

Response

{
  "result": "success",
  "data": {
    "publicId": "vat_th_abc123",
    "country": "ZW",
    "thresholdAmount": 7500000,
    "currency": "USD",
    "periodType": "annual",
    "alertAtPercentage": 90,
    "alertEmail": "finance@example.com",
    "registered": true,
    "registrationDate": "2026-03-01",
    "registrationNumber": "VAT-2026-001234",
    "createdAt": "2026-01-10T08:00:00Z",
    "updatedAt": "2026-03-07T14:30:00Z"
  }
}
GET/v1/get/revenueCalculator

Revenue Calculator

Calculate revenue metrics for your business including year-to-date revenue, rolling 12-month revenue, monthly average, and projected annual revenue. When a VAT threshold is configured, the response includes a comparison showing how close you are to the threshold.

Optional parameters

  • Name
    asOfDate
    Type
    string
    Description

    Calculate metrics as of this date (YYYY-MM-DD). Defaults to today.

Request

GET
/v1/get/revenueCalculator
curl "https://api.umbraerp.com/v1/get/revenueCalculator?asOfDate=2026-03-07" \
  -H "Authorization: Bearer <your_access_token>"

Response

{
  "result": "success",
  "data": {
    "ytdRevenue": 1250000,
    "rolling12MonthRevenue": 4800000,
    "monthlyAverage": 400000,
    "projectedAnnual": 4800000,
    "currency": "USD",
    "asOfDate": "2026-03-07",
    "vatThreshold": {
      "configured": true,
      "thresholdAmount": 7500000,
      "percentageReached": 64.0,
      "registered": true,
      "registrationNumber": "VAT-2026-001234"
    }
  }
}

Was this page helpful?