onboarding-goods-receipt-inspection-runs

Create a purchase order to receive goods against. Lines carry a sku, a description and an ordered whole-unit quantity. Over/under tolerances are whole percentages allowed above/below ordered before a GRN is flagged. Ids look like PO-0001. Free tier, full CRUD.

{
  "type": "object",
  "properties": {
    "reference": {
      "type": "string",
      "maxLength": 60,
      "description": "Your own purchase-order number"
    },
    "supplier": {
      "type": "string",
      "maxLength": 60,
      "description": "Who you ordered from"
    },
    "overTolerancePct": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100,
      "default": 10,
      "description": "Whole % extra allowed above ordered (default 10)"
    },
    "underTolerancePct": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100,
      "default": 10,
      "description": "Whole % short allowed below ordered (default 10)"
    },
    "lines": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "maxLength": 40,
            "description": "Stock-keeping unit / model code"
          },
          "description": {
            "type": "string",
            "maxLength": 160,
            "description": "What it is"
          },
          "ordered": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000,
            "description": "Whole units ordered"
          }
        },
        "required": [
          "sku",
          "description",
          "ordered"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 200,
      "description": "Lines on this purchase order"
    }
  },
  "required": [
    "reference",
    "supplier",
    "lines"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Create a goods-receipt note (GRN) against an open purchase order. Give one cell per PO line: the whole units received and/or damaged. received is checked against the line's ordered quantity and the PO's over tolerance; receiving past the over tolerance is refused unless declared damaged. Shortage is recorded automatically (ordered minus received, floored at zero) and shown as a discrepancy. Partial deliveries are fine: raise several GRNs against the same PO. Free tier, full CRUD.

{
  "type": "object",
  "properties": {
    "po": {
      "type": "string",
      "maxLength": 40,
      "description": "Purchase-order id or reference, e.g. PO-0001"
    },
    "receivedAt": {
      "type": "string",
      "maxLength": 10,
      "description": "ISO date of physical receipt (default today)"
    },
    "carrier": {
      "type": "string",
      "maxLength": 60,
      "description": "Delivered by"
    },
    "note": {
      "type": "string",
      "maxLength": 400,
      "description": "Memo for the whole GRN"
    },
    "lines": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "line": {
            "type": "string",
            "maxLength": 40,
            "description": "PO line to receive, e.g. L01"
          },
          "received": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000,
            "description": "Whole units of good stock"
          },
          "damaged": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000,
            "description": "Whole units received but damaged"
          },
          "shortage": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000,
            "description": "Whole units short; when you know the count"
          },
          "damageNote": {
            "type": "string",
            "maxLength": 400,
            "description": "What was damaged"
          },
          "shortageNote": {
            "type": "string",
            "maxLength": 400,
            "description": "Why it is short"
          }
        },
        "required": [
          "line",
          "received"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 200,
      "description": "Which PO lines you are receiving now"
    }
  },
  "required": [
    "po",
    "lines"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Add another PO line (or more units on a line already open on this GRN) to an existing open goods-receipt note. Useful when one delivery arrives in batches. The over-tolerance gate still applies to the PO line's cumulative received count across every GRN. Free tier, full CRUD.

{
  "type": "object",
  "properties": {
    "grn": {
      "type": "string",
      "maxLength": 40,
      "description": "Open GRN id, e.g. GRN-0001"
    },
    "line": {
      "type": "string",
      "maxLength": 40,
      "description": "PO line to receive, e.g. L01"
    },
    "received": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "description": "Whole units of good stock"
    },
    "damaged": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "description": "Whole units received but damaged"
    },
    "damageNote": {
      "type": "string",
      "maxLength": 400,
      "description": "What was damaged"
    },
    "shortageNote": {
      "type": "string",
      "maxLength": 400,
      "description": "Why it is short"
    }
  },
  "required": [
    "grn",
    "line",
    "received"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List goods-receipt notes, newest first, optionally filtered to one purchase order.

{
  "type": "object",
  "properties": {
    "po": {
      "type": "string",
      "maxLength": 40,
      "description": "Only GRNs against this purchase order"
    },
    "includeLines": {
      "type": "boolean",
      "default": false,
      "description": "Include line detail"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get a single goods-receipt note by id, with its lines, damage and shortage per line.

{
  "type": "object",
  "properties": {
    "grn": {
      "type": "string",
      "maxLength": 40,
      "description": "GRN id, e.g. GRN-0001"
    }
  },
  "required": [
    "grn"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List lines that are not as ordered: damaged units, a declared shortage, or received below the PO line's under tolerance. Optionally filter to one PO.

{
  "type": "object",
  "properties": {
    "po": {
      "type": "string",
      "maxLength": 40,
      "description": "Only discrepancies on this purchase order"
    },
    "includeResolved": {
      "type": "boolean",
      "default": false,
      "description": "Include GRNs that are closed (resolved)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Close an open GRN. A closed GRN can no longer take lines, and its discrepancies are treated as resolved. Closing is free-tier and never mutates the PO.

{
  "type": "object",
  "properties": {
    "grn": {
      "type": "string",
      "maxLength": 40,
      "description": "Open GRN id, e.g. GRN-0001"
    }
  },
  "required": [
    "grn"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Reconcile every purchase order against every GRN: open POs (not yet fully received), POs fully received within tolerance, POs with at least one discrepancy, and per-line open/short/damaged counts. Nothing is written.

{
  "type": "object",
  "properties": {
    "includeOnlyDiscrepancies": {
      "type": "boolean",
      "default": false,
      "description": "Only list POs with at least one discrepancy"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Pro. Export every GRN (or just one PO's GRNs) as CSV with a header row: grn,po,po_reference,received_at,carrier,status,line,sku,received,damaged,shortage,damage_note,shortage_note. Watermark-free and not truncated.

{
  "type": "object",
  "properties": {
    "po": {
      "type": "string",
      "maxLength": 40,
      "description": "Export GRNs for one purchase order only"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Report this endpoint's licence state for your token as JSON: the product, the tier free or pro, why it is not Pro, and the checkout URL. Call it to explain a free-tier refusal. No arguments, nothing changes.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Turn Pro on for this connection with key, an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. Data under your token stays; a wrong or expired key changes nothing. license_status confirms it.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "License key from checkout, MCPL1.<payload>.<signature>"
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}