API Docs

Global settings

Get invoices by market

Returns all MPower invoices from a selected market within a specified date range.

POST/https://api-get-invoices-by-market-kigtdz23uq-ew.a.run.app

Headers

Content-Type
application/json
string
x-api-key
<API_KEY>
string

Body Parameters

market_id
Required, not empty.
Tfojbvr0Gwikv0nfKkYy
string
status
Required. Must be one of DRAFT, ISSUED, CANCELLED, or ALL.
ALL
DRAFT | ISSUED | CANCELLED | ALL
start_date
Required date in strict YYYY-MM-DD format. Converted to a Unix timestamp in milliseconds using midnight UTC.
2026-01-01
string
end_date
Required date in strict YYYY-MM-DD format. Converted to a Unix timestamp in milliseconds using midnight UTC. The end date is exclusive.
2026-07-01
string

cURL

curl -i \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: <API_KEY>" \
  -d '{
    "market_id": "Tfojbvr0Gwikv0nfKkYy",
    "status": "ALL",
    "start_date": "2026-01-01",
    "end_date": "2026-07-01"
  }' \
  https://api-get-invoices-by-market-kigtdz23uq-ew.a.run.app

Response

200 Success

{
  "count": 1,
  "invoices": {
    "invoiceDocumentId": {
      "customer_data": {
        "customer_id": "customer-id",
        "customer_name": "Customer name"
      },
      "invoice_data": {
        "currency": "USD",
        "end_use_location": {
          "team_id": "team-id",
          "market_id": "market-id"
        },
        "invoice_date": 1779573600000,
        "invoice_number": "INV-001",
        "sales_type": "EXTERNAL"
      },
      "market_id": "market-id",
      "team_id": "team-id",
      "value": 123.45
    }
  }
}

200 No invoices found

{
  "count": 0,
  "invoices": {}
}

400 Invalid payload

{
  "success": false,
  "message": "Invalid payload",
  "errors": [
    {
      "path": "status",
      "message": "Invalid option: expected one of \"DRAFT\"|\"ISSUED\"|\"CANCELLED\"|\"ALL\""
    }
  ]
}

401 Unauthorized

{
  "error": "Unauthorized"
}

403 Origin not allowed

{
  "error": "Origin not allowed"
}

405 Method not allowed

{
  "error": "Method not allowed"
}

500 API key is not configured

{
  "error": "API key is not configured"
}

Behavior / Side effects

Read-only endpoint

  • Reads documents from the invoices collection.
  • Does not create, update, or delete Firestore documents.

Request behavior

  • Requires a JSON body with market_id, status, start_date, and end_date.
  • Does not support additional filters, sorting, or pagination.
  • Returns all invoices matching the filters in a single response.

Query behavior

  • market_id is matched against invoices/{invoice_id}.market_id.
  • start_date is converted to midnight UTC and used as sales_info.date_of_invoice >= start_date.
  • end_date is converted to midnight UTC and used as sales_info.date_of_invoice < end_date.
  • end_date is exclusive.
  • status is matched against invoices/{invoice_id}.status unless status is ALL.
  • If status is ALL, only the status filter is omitted.

Response shape

  • Returns a top-level count.
  • Returns a top-level invoices object.
  • Each key inside invoices is the Firestore invoice document ID.
  • Each invoice includes customer_data, invoice_data, market_id, team_id, and value.
  • invoice_data includes currency, invoice_date, invoice_number, and sales_type.
  • invoice_data.end_use_location can be an object or null.

Field mapping

  • customer_data.customer_id is read from invoices/{invoice_id}.customer_info.id.
  • customer_data.customer_name is read from invoices/{invoice_id}.customer_info.name.
  • invoice_data.currency is read from invoices/{invoice_id}.currency.
  • invoice_data.end_use_location is read from invoices/{invoice_id}.general_config.end_use_team.
  • invoice_data.end_use_location.team_id is read from invoices/{invoice_id}.general_config.end_use_team.id.
  • invoice_data.end_use_location.market_id is read from invoices/{invoice_id}.general_config.end_use_team.market_id.
  • invoice_data.invoice_date is read from invoices/{invoice_id}.sales_info.date_of_invoice.
  • invoice_data.invoice_number is read from invoices/{invoice_id}.payment_ref.ref.
  • invoice_data.sales_type is read from invoices/{invoice_id}.sales_info.type.
  • market_id is read from invoices/{invoice_id}.market_id.
  • team_id is read from invoices/{invoice_id}.team_id.
  • value is calculated by summing all invoices/{invoice_id}.lines.{line_id}.amount values.

Data quality expectations

  • Mapped string and number fields are expected to be present in Firestore.
  • If a mapped string or number field is missing or has an invalid type, the API returns null for that field.
  • Expected sales_type values are EXTERNAL or INTERCO.
  • If sales_info.type is missing or is not a valid non-empty string, sales_type is returned as null.
  • If another string value appears, the API returns it as stored.
  • invoice_data.end_use_location is returned as null when general_config.end_use_team.id is missing or is not a valid non-empty string.
  • If general_config.end_use_team.id exists but market_id is missing or invalid, end_use_location.market_id is returned as null.
  • For value, missing or invalid amount values contribute 0.
  • If lines is missing or is not an object, value is 0.