Goods Received / Item Receipt

Overview

The Goods Received API allows your ERP or warehouse management system to send item receipt confirmations to SoftCo, enabling three-way matching between purchase orders, goods receipts, and supplier invoices. For organisations where receipting_required is set to true on a purchase order line, SoftCo will hold the corresponding invoice for approval until a matching goods receipt has been received through this API — ensuring that payment is only authorised for goods and services that have actually been delivered.

A single call to POST /goods-received/v1 submits one or more goods receipt records. Each record carries a GRN header with receipt details and supplier information, and a rows array of line items. Crucially, the po_number reference is carried at line level — not on the header — which means a single GRN can acknowledge receipt of items from multiple purchase orders in one submission. SoftCo matches each line against the relevant PO using the combination of po_number and line_number.

Where Goods Received fits in the AP workflow

Once a purchase order is in SoftCo and a supplier sends an invoice, the three-way matching process checks whether the invoiced items have actually arrived. When your team books a goods receipt or confirms service delivery in your ERP, that confirmation needs to reach SoftCo via this API. Without it, invoices on PO lines with receipting required will remain on hold, pending confirmation. Sending timely GRN data therefore directly affects how quickly invoices can be approved and paid.

When to call this endpoint

Quick Start

Here is the minimum viable GRN — a single receipt with two line items acknowledging delivery against a purchase order. The required header fields are grn_number, grn_date, and grn_supplier_number. Each line in the rows array requires row_id, line_number, po_number, quantity_received, and uom.

POST /goods-received/v1
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",
        "grn_number":         "GRN-2024-04521",
        "grn_date":           "2024-03-18",
        "grn_supplier_number": "SUP-001234",
        "grn_supplier_name":   "Acme Office Supplies Ltd",
        "received_by":         "Ciara Brennan",
        "rows": [
            {
              "row_id":            "1",
              "line_number":       1,
              "po_number":         "PO-2024-00891",
              "item_number":       1,              
              "item_description":  "A4 Copy Paper — 5 Ream Box",
              "quantity_received": 10,
              "uom":               "BOX"
            },
            {
              "row_id":            "2",
              "line_number":       2,
              "po_number":         "PO-2024-00891",
              "item_number":       4,              
              "item_description":  "Printer Ink Cartridge — Black",
              "quantity_received": 5,
              "uom":               "EA"
            }
          ]
        }
      ]
    }
  }
}

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

POST /goods-received/v1

Submit one or more goods receipt records to SoftCo. Each record carries GRN header information and a rows array of line items. Each line identifies the purchase order it is fulfilling via po_number and the quantity delivered via quantity_received. SoftCo matches these against the corresponding PO lines and releases any held invoices once the receipt is confirmed.

Request Headers

Request Body

The Goods Received API uses the standard SoftCo iPaaS envelope: objects → object → record. For all GRN requests, record is a JSON array with line items nested inside a rows as a JSON array.

Single goods receipt

Batch (multiple goods receipts)

Field Reference

The Goods Received API carries 62 fields across two levels: GRN header fields that apply to the entire receipt document, and line item fields within the rows array. The header includes groups for receipt identity, shipping documents, supplier details, receiving site, and optional custom extensibility fields.

GRN Header Fields

These fields sit directly within the record object and describe the goods receipt document as a whole.

Shipping Document Fields

These fields capture the reference numbers and dates from the shipping and delivery documentation accompanying the goods. They provide an audit trail linking the goods receipt back to the supplier's dispatch documents.

Supplier Fields

Supplier fields identify the vendor from whom the goods were received. grn_supplier_number is the required reference; the remaining fields carry address and identification detail for the supplier as recorded in your ERP at the time of receipt.

Receiving Site Fields

These fields identify the physical location where the goods were received. For organisations with multiple sites or warehouses, sending site details allows SoftCo to associate the receipt with the correct receiving location.

Custom Extensibility Fields

The GRN schema includes three groups of generic extensibility fields for carrying customer-specific metadata that does not map to a standard field. These are intended for organisations that need to pass additional context from their ERP through to SoftCo — for example internal reference codes, custom dates, or monetary values specific to their receiving process. Use only the fields your implementation requires; unused fields can be omitted.

Line Item Fields (rows array)

Line item fields are nested inside the rows array within the GRN record. Each element of the array represents one received line — with its own PO reference, quantity, unit of measure, and optional accounting coding. Every GRN must contain at least one line item.

Example Requests

Single GRN with full shipping document detail

POST /goods-received/v1
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",
        "system":               "NetSuite",
        "grn_number":           "GRN-2024-04521",
        "grn_date":             "2024-03-18",
        "received_by":          "Ciara Brennan",
        "delivery_slip":        "DS-ACM-20240318",
        "delivery_slip_date":   "2024-03-18",
        "packing_slip_number":  "PKG-44221",
        "grn_supplier_number":  "SUP-001234",
        "grn_supplier_name":    "Acme Office Supplies Ltd",
        "grn_supplier_city":    "Dublin",
        "grn_supplier_country": "Ireland",
        "site_name":            "Dublin Distribution Centre",
        "site_number":             "SITE-003",
        "grn_comment":          "All items received in good condition",
        "rows": [
            {
              "row_id":             "1",
              "line_number":        1,
              "po_number":          "PO-2024-00891",
              "item_number":        1,
              "item_description":   "A4 Copy Paper — 5 Ream Box",
              "quantity_received":  10,
              "uom":                "BOX",
              "accounting_object_1":"CC-ADMIN"
            },
            {
              "row_id":             "2",
              "line_number":        2,
              "po_number":          "PO-2024-00891",
              "item_number":        2,
              "item_description":   "Printer Ink Cartridge — Black",
              "quantity_received":  5,
              "uom":                "EA",
              "accounting_object_1":"CC-ADMIN"
            }
          ]
        }
      ]
    }
  }
}

Multi-PO receipt — one GRN covering lines from two purchase orders

{
  "objects": {
    "object": {
      "record": [
        {      
        "grn_number":          "GRN-2024-04522",
        "grn_date":            "2024-03-18",
        "grn_supplier_number": "SUP-001234",
        "received_by":         "Ciara Brennan",
        "rows": [
            {
              "row_id": "1", "line_number": 1,
              "po_number": "PO-2024-00891",
              "item_number": 1, "item_description": "A4 Copy Paper",
              "quantity_received": 10, "uom": "BOX"
            },
            {
              "row_id": "2", "line_number": 2,
              "po_number": "PO-2024-00892", // different PO on same delivery
              "item_number": 1, "item_description": "IT Consulting Services — Day 1",
              "quantity_received": 1, "uom": "DAY"
            }
          ]
        }
      ]
    }
  }
}

Batch — multiple GRNs in one request

{
  "objects": {
    "object": {
      "record": [
        {
          "grn_number": "GRN-2024-04521", "grn_date": "2024-03-18",
          "grn_supplier_number": "SUP-001234",
          "rows": [ { "row_id": "1", "line_number": 1, "po_number": "PO-2024-00891", "item_number": 1, "quantity_received": 10, "uom": "BOX" } ]
        },
        {
          "grn_number": "GRN-2024-04523", "grn_date": "2024-03-18",
          "grn_supplier_number": "SUP-000876",
          "rows": [ { "row_id": "1", "line_number": 1, "po_number": "PO-2024-00892", "item_number": 1, "quantity_received": 8, "uom": "DAY" } ]
        }
      ]
    }
  }
}

Validation

Every request is validated against the GRN 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

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

Troubleshooting

The most common error scenarios and how to resolve them.

Example Responses

Success — 202 Accepted

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

Partial success — 207 Multi-Status

{
  "status":      "PARTIAL",
  "total":       3,
  "succeeded":   2,
  "failed":      1,
  "errors":      [{ "index": 1, "error": "required key [grn_supplier_number] not found" }],
  "message":     "2 of 3 records processed successfully. 1 record failed validation."
}

Validation failure — 400 Bad Request

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

Authentication failure — 401 Unauthorized

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

What's Next

Goods Received completes the inbound transaction API set. Together with the Purchase Orders API, it enables full three-way matching in SoftCo — ensuring every invoice is validated against both a committed purchase order and a confirmed delivery before it can be approved for payment.

Transaction Data APIs

Master Data APIs