Purchase Orders v2

Overview

SoftCo supports two invoicing models. For non-PO invoices — expenses, ad-hoc services, or spend that does not require a formal commitment — invoices are coded and approved directly within SoftCo without any upstream purchase order. For PO-based invoices — where your organisation's procurement policy requires a purchase order before a supplier can invoice — SoftCo needs visibility of those POs from your ERP in order to validate and match against them. This API serves that second scenario.

The Purchase Orders API lets your ERP push purchase order data directly into SoftCo's AP platform, making each PO available for automated invoice matching. Once a PO is received, SoftCo can compare incoming supplier invoices against the committed quantities, unit prices, and GL coding on the order — reducing manual coding effort and accelerating invoice processing. Organisations using three-way matching can additionally pair this with the Goods Received API, requiring a confirmed receipt before an invoice can be approved.

A single call to POST /purchase-orders/v2 submits one or more complete purchase orders. Each order has a three-level structure: a PO header with order details and supplier information; one or more order lines in the rows array carrying pricing and quantities; and one or more coding rows in the coding array within each line, carrying the GL and cost-centre distribution for that line.

Where Purchase Orders fit in the AP workflow

SoftCo's AP platform is the system of record for invoice processing. When a supplier invoice arrives that references a purchase order, SoftCo looks up the PO your ERP has already sent via this API and compares the invoice against it — validating the supplier, quantities, and unit prices. Invoices that match within tolerance can be auto-approved; those outside tolerance are routed for review. For organisations that also use non-PO invoicing, both flows coexist: PO-referenced invoices are matched automatically, while non-PO invoices follow a direct coding and approval workflow. The richer the PO data you send, the more effectively SoftCo can automate the matching process.

When to call this endpoint

Quick Start

The minimum viable v2 PO request — a single order with two line items, each with a single coding row. Copy this, swap in your credentials and real PO data, and send. The required fields at header level are po_number, supplier_number, and po_date. Each line in the rows array requires line_number, quantity, unit, unit_price, unit_price_is_net, row_handling_style, partial_invoice_indicator, and tolerence_group. Each coding row requires posting_line, distribution_percentage, quantity, coding_net_amount, coding_gross_amount, coding_tax_code, and gl_code.

POST /purchase-orders/v2
x-api-key:     your-api-key-here
Content-Type:  application/Json
Client_Id:     your-client-id
Client_Secret: your-client-secret

{
  "objects": {
    "object": {
      "record": [
        {
          "organization":         "main",
          "po_number":            "PO-2024-00891",
          "po_date":              "2024-03-15",
          "supplier_number":      "SUP-001234",
          "supplier_name":        "Acme Office Supplies Ltd",
          "currency":             "EUR",
          "po_net_total":         1250.00,
          "po_gross_total":       1537.50,
          "rows": [
            {
              "line_number":             1,
              "line_description":         "A4 Copy Paper — 5 Ream Box",
              "quantity":                10,
              "unit":                    "BOX",
              "unit_price":              62.50,
              "unit_price_is_net":       "true",
              "row_net_total":            625.00,
              "row_handling_style":      "GRN_LEVEL_MATCH",
              "partial_invoice_indicator": "DISTRIBUTE_PROPORTIONALLY",
              "tolerence_group":         "default",
              "coding": [
                {
                  "posting_line":           1,
                  "distribution_percentage": 100,
                  "gl_code":                "6100",
                  "quantity":               10,
                  "coding_net_amount":      625.00,
                  "coding_gross_amount":    768.75,
                  "coding_tax_code":        "T1"
                }
              ]
            },
            {
              "line_number":             2,
              "line_description":         "Printer Ink Cartridge — Black",
              "quantity":                5,
              "unit":                    "EA",
              "unit_price":              125.00,
              "unit_price_is_net":       "true",
              "row_net_total":            625.00,
              "row_handling_style":      "GRN_LEVEL_MATCH",
              "partial_invoice_indicator": "DISTRIBUTE_PROPORTIONALLY",
              "tolerence_group":         "default",
              "coding": [
                {
                  "posting_line":           1,
                  "distribution_percentage": 100,
                  "gl_code":                "6100",
                  "quantity":               5,
                  "coding_net_amount":      625.00,
                  "coding_gross_amount":    768.75,
                  "coding_tax_code":        "T1"
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

A successful response looks like this:

{
  "status":      "SUCCESS",
  "total":       1,
  "succeeded":   1,
  "failed":      0,
  "errors":      [],
  "message":     "All records processed successfully."
}

How It Works

Every request follows the same pipeline. Your system sends once — validation, transformation, and delivery to SoftCo are handled automatically.

Authentication

All requests require an API key and OAuth 2.0 credentials. Your credentials are provided during onboarding — keep them secure and never expose them in client-side code or version control.

Requests with a missing or invalid API key are rejected by the gateway immediately and never reach the integration layer.

Required Headers

Response Codes

Endpoint

Submit one or more purchase orders in the v2 unified format. Each record in the batch is validated independently — a single failing record does not block the rest.

Request Headers

Request Body

The payload uses a fixed three-level JSON envelope. The record array can contain one PO or a batch of multiple POs.

Coding Rows

Coding rows are the key difference between v1 and v2. Each order line in v2 must include at least one coding row in its coding array. Coding rows carry the GL account code, accounting objects (cost centres, departments, projects), and the percentage of the line value that should be allocated to each account.

Simple case — no split (single coding row)

When the full value of a line is charged to a single GL account, include exactly one coding row with distribution_percentage: 100. The coding row amounts should match the parent line amounts.

Split case — multiple coding rows

When a line's cost is shared between departments or projects, include one coding row per split. Each row carries its own GL code, accounting objects, and the percentage it represents. The system validates that all distribution_percentage values for a given line sum to exactly 100.

Coding row amounts

Set coding_net_amount and coding_gross_amount to the portion of the line value that corresponds to this coding row's percentage. For a line with row_net_total: 1000 split 60/40, the first coding row should have coding_net_amount: 600 and the second coding_net_amount: 400.

Field Reference

PO Header Fields

Supplier Fields

Address Fields

Both the delivery address and invoice address are optional. All address fields use the prefixes delivery_ and invoice_ respectively. Note that the description field for each address block uses the field name delivery_address_description and invoice_address_description.

Custom Header Fields

The v2 PO header supports custom label, date, and amount fields for ERP-specific data that does not map to a standard field.

Line Item Fields (rows[])

Coding Row Fields (rows[].coding[])

Example Requests

Single PO with split coding

This example shows a two-line PO where line 1 is split 40%/60% across two GL accounts, and line 2 is fully charged to one account.

{
  "objects": { "object": { "record": [{
    "organization":  "main",
    "system":        "NetSuite",
    "po_number":     "PO-2024-00891",
    "po_type":       "NEW",
    "posting_date":  "2024-03-15",
    "po_date":       "2024-03-15",
    "delivery_date": "2024-03-18",
    "currency":      "EUR",
    "description":   "Office Supplies from Acme",
    "created_by":    "Jane Murphy",
    "po_net_total":  1625.00,
    "po_gross_total": 1625.00,
    "supplier_number": "SUP-001234",
    "supplier_name":  "Acme Office Supplies Ltd",
    "rows": [
      {
        "line_number":     1,
        "line_description": "A4 Copy Paper — 5 Ream Box",
        "product_code":    "72110",
        "quantity":        10,
        "unit":            "BOX",
        "unit_price":      100.00,
        "unit_price_is_net": "true",
        "row_net_total":   1000.00,
        "tax_code":        "T1",
        "row_gross_total":  1000.00,
        "coding": [
          { "posting_line": 1, "distribution_percentage": 40, "gl_code": "6100", "coding_net_amount": 400.00, "coding_tax_code": "T1", "coding_gross_amount": 400.00 },
          { "posting_line": 2, "distribution_percentage": 60, "gl_code": "6200", "coding_net_amount": 600.00, "coding_tax_code": "T1", "coding_gross_amount": 600.00 }
        ]
      },
      {
        "line_number":     2,
        "line_description": "Printer Ink Cartridge — Black",
        "product_code":    "72120",
        "quantity":        5,
        "unit":            "EA",
        "unit_price":      125.00,
        "unit_price_is_net": "true",
        "row_net_total":   625.00,
        "tax_code":        "T1",
        "row_gross_total":  625.00,
        "coding": [
          { "posting_line": 1, "distribution_percentage": 100, "gl_code": "6100", "coding_net_amount": 625.00, "coding_tax_code": "T1", "coding_gross_amount": 625.00 }
        ]
      }
    ]
  }] }}
}

Validation

Every request is validated against the purchase order schema before any processing takes place. If validation fails, the entire request is rejected immediately — nothing is queued or forwarded to SoftCo. You receive a clear error identifying the field or structural issue.

What is checked

Validation error response

When validation fails, the API returns a 400 Bad Request with a JSON body identifying the failing field or structure:

{
  "status":      "FAILED",
  "total":       1,
  "succeeded":   0,
  "failed":      1,
  "errors":      [{ "index": 0, "error": "required key [po_number] not found" }],
  "message":     "1 of 1 records failed validation."
}

The errors array identifies the exact field or path that failed, and the message field provides a summary. Fix the identified issue and resubmit.

Troubleshooting

Example Responses

Success — 202 Accepted

{
  "status":      "SUCCESS",
  "total":       1,
  "succeeded":   1,
  "failed":      0,
  "errors":      [],
  "message":     "All records processed successfully."
}

Validation failure — 400 Bad Request

{
  "status":      "FAILED",
  "total":       1,
  "succeeded":   0,
  "failed":      1,
  "errors":      [{ "index": 0, "error": "required key [supplier_number] not found" }],
  "message":     "1 of 1 records failed validation."
}

Authentication failure — 401 Unauthorized

{
  "status":   "FAILED",
  "message":  "Unauthorized"
}

What's Next

Transaction Data APIs

Master Data APIs