The Spend Lifecycle

note

A map of which API endpoints fire in which order. For the object model the stages write into (legal entities, org units, cost centers, users, permission sets, export configuration), read Core Concepts first.

A single piece of indirect spend (a software license, a piece of office equipment, a consulting engagement) moves through a fixed sequence of stages on the SpendOne platform. Each stage creates or updates a specific entity and is exposed as a distinct part of the API.

This page walks through that sequence end-to-end.

Stages at a Glance

1. Need

A user identifies a need to spend money: renewing a SaaS subscription, ordering hardware, hiring a contractor.

• Trigger: human action in the dashboard, or a renewal reminder for an existing subscription.
• Entity created: none yet.
• API surface: none; the need exists outside the system until step 2.

2. Purchase Request

The need is captured as a structured request: requester, items, supplier (existing or proposed), cost center, estimated amount, and supporting documents (e.g. a quote PDF).

• Trigger: user submits the request form, or the platform creates a request automatically from a subscription renewal.
• Entity created: PurchaseRequest.
• API surface: /api/v1/purchase-requests.

If a quote PDF is attached, document extraction (see AI Capabilities) pre-fills the request fields.

3. Approval

The approval engine evaluates the configured rules against the request (amount, cost center, supplier, requester) and routes it to the right approvers in the right order.

• Trigger: request submission.
• Entity created: Approval (with one or more steps).
• API surface: /api/v1/approvals/tasks and /api/v1/approvals/{code}/tasks. The rules that produce the plan are managed under /api/v1/rules.

Each approver acts on their step (approve, reject, request changes). When all steps pass, the request becomes approved.

4. Purchase Order

An approved request is converted into a purchase order sent to the supplier. Depending on configuration, this can be one-to-one or aggregated.

• Trigger: all approval steps pass.
• Entity created: PurchaseOrder, linked back to the originating request.
• API surface: /api/v1/purchase-orders.

5. Supplier Delivery

The supplier delivers the goods or service. SpendOne tracks delivery state and, where applicable, ingests delivery notes.

• Trigger: supplier ships, or a delivery note PDF arrives via email or upload.
• Entity created/updated: DeliveryNote (optional) and updates on the PurchaseOrder state.
• API surface: /api/v1/purchase-orders/{code}. Delivery notes have no public endpoint; receipt is recorded through POST /api/v1/purchase-orders/{code}/receive.

6. Invoice Ingestion

The supplier sends an invoice. It enters the platform through one of three channels:

1. Forwarded to the tenant inbox: a server-side worker watches the configured inbox, downloads PDF attachments, and processes them.
2. Uploaded by a user in the dashboard.
3. Pushed via API by an integrator.

In all three cases, the document goes through AI-based extraction, which produces structured fields: supplier, invoice number, dates, line items, tax breakdown, totals, and PO references found in the document.

• Entity created: Invoice in an unprocessed state.
• API surface: /api/v1/invoices. Extraction runs automatically on upload; POST /api/v1/invoices/{code}/reprocess re-runs it.

7. Invoice Approval

The platform matches the invoice against existing purchase orders, subscriptions, and credit-card transactions, then routes it through the approval engine.

• Trigger: extraction completes.
• What happens: the platform runs PO-number matching, recipient matching, semantic matching, tax validation, and subscription amount checks. Matches are presented as suggestions; humans confirm.
• Entity updated: Invoice moves through substeps (matched → approved). Approval steps are created by the same approvals engine used for requests.
• API surface: /api/v1/invoices/{code} and /api/v1/approvals/tasks.

8. Accounting Export

Once approved, the invoice is mapped to a journal entry: cost center, GL accounts, tax codes, debit/credit lines. The mapping is exported to the customer's accounting system.

• Trigger: invoice approval completes.
• Entity created: a journal entry, readable under /api/v1/journal-entries.
• API surface: see the Accounting System Integration guide.

9. Payment

The invoice is paid via the configured payment method (SEPA transfer, corporate card, direct debit). For card spend, the invoice is linked to the card transaction that already settled it.

• Trigger: approval and accounting export complete; payment terms are due.
• Entity updated: Invoice.paid and Invoice.workflow_status; on the card path, the matched CreditCardTransaction.
• API surface: /api/v1/payment-methods and /api/v1/credit-cards/....

10. Reconciliation

The reconciliation service continuously checks that the world is consistent: every approved PO has an invoice or is closed, every card transaction has a matching invoice, no duplicates exist.

• Trigger: runs continuously and on relevant events, as the reconciliation substep of invoice review.
• Entity updated: flags on invoices, POs, and card transactions; surfaces unresolved items as accountant tasks.
• API surface: accountant-tasks endpoints and reconciliation views.

11. Audit

Every state change above is recorded in the audit log: who did what, when, on which entity, with what before/after state.

• Entity created: an append-only audit log entry, readable under /api/v1/audit-logs.
• API surface: audit log query endpoints.

Mapping Stages to API Calls

For an integrator, a typical happy-path sequence looks like this:

Stage	HTTP call (illustrative)
Create request	POST /api/v1/purchase-requests
Submit for approval	POST /api/v1/purchase-requests/{code}/request-approval
Approve step	POST /api/v1/approvals/{code}/tasks/{id}/approve
Create PO	no call; the platform creates it when the request is fully approved
Upload invoice	POST /api/v1/invoices (multipart with PDF)
Re-run extraction	POST /api/v1/invoices/{code}/reprocess
Approve invoice	POST /api/v1/approvals/{code}/tasks/{id}/approve
Export to accounting	exposed per accounting system; see integration guide

The exact shapes are documented in the API reference. The point of this page is the order: once you have the order, the API reference fills in the parameters.