{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/api-search/coupa/json-schema/coupa-purchase-order-schema.json",
  "title": "Coupa Purchase Order",
  "description": "Schema representing a Coupa purchase order, which is a commitment to purchase goods or services from a supplier. Based on the Coupa Core API purchase orders resource as documented at compass.coupa.com.",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Coupa unique internal identifier for the purchase order.",
      "readOnly": true
    },
    "po-number": {
      "type": "string",
      "description": "Purchase order number. May be auto-generated by Coupa or provided externally.",
      "maxLength": 20
    },
    "status": {
      "type": "string",
      "description": "Current status of the purchase order in its lifecycle.",
      "enum": [
        "buyer_hold",
        "cancelled",
        "closed",
        "currency_hold",
        "draft",
        "error",
        "expensed",
        "issued",
        "supplier_hold",
        "supplier_window_hold",
        "exported"
      ]
    },
    "type": {
      "type": "string",
      "description": "Order type classification. ExternalOrderHeader for externally created purchase orders.",
      "enum": [
        "ExternalOrderHeader"
      ]
    },
    "version": {
      "type": "integer",
      "description": "PO supplier version number. Increments when revisions are sent to the supplier."
    },
    "internal-revision": {
      "type": "integer",
      "description": "Internal revision number. Increases each time a change is made to the purchase order.",
      "readOnly": true
    },
    "change-type": {
      "type": ["string", "null"],
      "description": "Indicates the last modification method applied to the purchase order.",
      "enum": ["change", "revision", "confirmation", null]
    },
    "confirmation_status": {
      "type": ["string", "null"],
      "description": "Current confirmation state from the supplier.",
      "enum": ["pending_supplier_action", "confirmed", "partially_confirmed", "completed", "rejected", null]
    },
    "acknowledged-flag": {
      "type": "boolean",
      "description": "Indicates whether the purchase order has been acknowledged by the supplier."
    },
    "acknowledged-at": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "Timestamp when the purchase order was acknowledged by the supplier."
    },
    "total": {
      "type": ["number", "null"],
      "description": "Total monetary amount of the purchase order, calculated from order lines.",
      "readOnly": true
    },
    "currency": {
      "$ref": "#/$defs/CurrencyReference",
      "description": "Transaction currency for the purchase order."
    },
    "supplier": {
      "$ref": "#/$defs/SupplierReference",
      "description": "The supplier (vendor) associated with this purchase order."
    },
    "supplier-site": {
      "$ref": "#/$defs/SupplierSiteReference",
      "description": "Specific supplier site or location for the order."
    },
    "requester": {
      "$ref": "#/$defs/UserReference",
      "description": "The user who requested the purchase order."
    },
    "ship-to-address": {
      "$ref": "#/$defs/AddressReference",
      "description": "Delivery destination address for the ordered goods or services."
    },
    "ship-to-attention": {
      "type": ["string", "null"],
      "description": "Recipient contact name at the shipping address.",
      "maxLength": 255
    },
    "ship-to-user": {
      "$ref": "#/$defs/UserReference",
      "description": "Designated user to receive the goods."
    },
    "payment-term": {
      "$ref": "#/$defs/PaymentTermReference",
      "description": "Payment schedule terms for the purchase order."
    },
    "payment-method": {
      "type": ["string", "null"],
      "description": "Payment processing method for the order.",
      "enum": ["invoice", "pcard", "invoice_only", "pcard_only", "virtual_card", null]
    },
    "shipping-term": {
      "$ref": "#/$defs/ShippingTermReference",
      "description": "Shipping and delivery terms for the purchase order."
    },
    "order-lines": {
      "type": "array",
      "description": "Collection of line items on the purchase order.",
      "items": {
        "$ref": "#/$defs/OrderLine"
      }
    },
    "requisition-header": {
      "type": ["object", "null"],
      "description": "Reference to the source requisition that generated this purchase order.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Coupa unique identifier of the source requisition."
        }
      }
    },
    "invoice-stop": {
      "type": "boolean",
      "description": "When true, invoicing is blocked for this purchase order."
    },
    "exported": {
      "type": "boolean",
      "description": "Indicates whether the purchase order has been exported to an external system (e.g., ERP)."
    },
    "last-exported-at": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "Timestamp when the purchase order was last exported."
    },
    "hide-price": {
      "type": "boolean",
      "description": "Supplier-facing price visibility control. When true, prices are hidden from the supplier."
    },
    "price-hidden": {
      "type": "boolean",
      "description": "Indicates whether pricing is currently hidden from the supplier."
    },
    "transmission-method-override": {
      "type": ["string", "null"],
      "description": "Override for the default PO transmission method to the supplier.",
      "enum": ["supplier_default", "email", "cxml", "xml", "do_not_transmit", null]
    },
    "transmission-status": {
      "type": ["string", "null"],
      "description": "Current delivery/transmission status of the purchase order.",
      "enum": ["sent_via_email", "sent_via_cxml", "sent_via_xml", "pending", "not_sent", null]
    },
    "transmission-emails": {
      "type": ["string", "null"],
      "description": "Comma-separated list of email addresses used for PO transmission."
    },
    "coupa-accelerate-status": {
      "type": ["string", "null"],
      "description": "Status indicating whether the associated invoice has discount payment terms."
    },
    "classification": {
      "type": ["string", "null"],
      "description": "Order classification category.",
      "enum": ["msp", "supplier", "vms", null]
    },
    "confirm-by-hrs": {
      "type": ["integer", "null"],
      "description": "Number of hours the supplier has to confirm the purchase order."
    },
    "order-confirmation-level": {
      "type": ["integer", "null"],
      "description": "Confirmation depth indicator (0=not_applicable, 1=header, 2=line)."
    },
    "attachments": {
      "type": "array",
      "description": "File attachments linked to the purchase order.",
      "items": {
        "$ref": "#/$defs/AttachmentReference"
      }
    },
    "milestones": {
      "type": "array",
      "description": "Procurement milestone markers associated with the purchase order.",
      "items": {
        "$ref": "#/$defs/MilestoneReference"
      }
    },
    "pcard": {
      "type": ["object", "null"],
      "description": "Purchasing card reference for the order.",
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "created-at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp when the purchase order was created. Automatically set by Coupa.",
      "readOnly": true
    },
    "updated-at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp when the purchase order was last updated. Automatically set by Coupa.",
      "readOnly": true
    },
    "created-by": {
      "$ref": "#/$defs/UserReference",
      "description": "The user who created the purchase order."
    },
    "updated-by": {
      "$ref": "#/$defs/UserReference",
      "description": "The user who last updated the purchase order."
    }
  },
  "required": [
    "type",
    "supplier",
    "currency",
    "order-lines"
  ],
  "$defs": {
    "UserReference": {
      "type": "object",
      "description": "Reference to a Coupa user.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Coupa unique identifier for the user."
        },
        "login": {
          "type": "string",
          "description": "User login name."
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "User email address."
        }
      }
    },
    "SupplierReference": {
      "type": "object",
      "description": "Reference to a supplier (vendor) in Coupa.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Coupa unique identifier for the supplier."
        },
        "name": {
          "type": "string",
          "description": "Supplier name.",
          "maxLength": 100
        },
        "number": {
          "type": "string",
          "description": "Supplier number."
        }
      }
    },
    "SupplierSiteReference": {
      "type": "object",
      "description": "Reference to a supplier site or location.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Coupa unique identifier for the supplier site."
        },
        "name": {
          "type": "string",
          "description": "Supplier site name."
        }
      }
    },
    "CurrencyReference": {
      "type": "object",
      "description": "Reference to a currency.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Coupa unique identifier for the currency."
        },
        "code": {
          "type": "string",
          "description": "ISO 4217 currency code.",
          "pattern": "^[A-Z]{3}$",
          "examples": ["USD", "EUR", "GBP"]
        }
      }
    },
    "AddressReference": {
      "type": "object",
      "description": "Reference to a physical address in Coupa.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Coupa unique identifier for the address."
        },
        "name": {
          "type": "string",
          "description": "Address name or label."
        },
        "street1": {
          "type": "string",
          "description": "Street address line 1."
        },
        "street2": {
          "type": ["string", "null"],
          "description": "Street address line 2."
        },
        "city": {
          "type": "string",
          "description": "City name."
        },
        "state": {
          "type": ["string", "null"],
          "description": "State or province."
        },
        "postal-code": {
          "type": ["string", "null"],
          "description": "Postal or ZIP code."
        },
        "country": {
          "type": "object",
          "description": "Country reference.",
          "properties": {
            "id": {
              "type": "integer"
            },
            "code": {
              "type": "string",
              "description": "ISO 3166-1 alpha-2 country code."
            }
          }
        }
      }
    },
    "PaymentTermReference": {
      "type": "object",
      "description": "Reference to a payment term definition.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Coupa unique identifier for the payment term."
        },
        "code": {
          "type": "string",
          "description": "Payment term code."
        }
      }
    },
    "ShippingTermReference": {
      "type": "object",
      "description": "Reference to a shipping term definition.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Coupa unique identifier for the shipping term."
        },
        "code": {
          "type": "string",
          "description": "Shipping term code."
        }
      }
    },
    "OrderLine": {
      "type": "object",
      "description": "A line item on a purchase order representing a specific good or service being ordered.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Coupa unique identifier for the order line.",
          "readOnly": true
        },
        "line-num": {
          "type": "integer",
          "description": "Sequential line number."
        },
        "description": {
          "type": "string",
          "description": "Description of the item or service.",
          "maxLength": 255
        },
        "quantity": {
          "type": "number",
          "description": "Quantity ordered."
        },
        "price": {
          "type": "number",
          "description": "Unit price of the item."
        },
        "total": {
          "type": "number",
          "description": "Line total (quantity multiplied by price).",
          "readOnly": true
        },
        "uom": {
          "type": "object",
          "description": "Unit of measure.",
          "properties": {
            "id": {
              "type": "integer"
            },
            "code": {
              "type": "string",
              "description": "Unit of measure code (e.g., EA, CS, BX)."
            }
          }
        },
        "need-by-date": {
          "type": ["string", "null"],
          "format": "date-time",
          "description": "Date by which the item is needed."
        },
        "source-part-num": {
          "type": ["string", "null"],
          "description": "Supplier part number.",
          "maxLength": 255
        },
        "supplier-aux-part-num": {
          "type": ["string", "null"],
          "description": "Supplier auxiliary part number."
        },
        "commodity": {
          "type": ["object", "null"],
          "description": "Commodity classification for the line item.",
          "properties": {
            "id": {
              "type": "integer"
            },
            "name": {
              "type": "string"
            }
          }
        },
        "account": {
          "type": ["object", "null"],
          "description": "Chart of accounts reference for cost allocation.",
          "properties": {
            "id": {
              "type": "integer"
            },
            "code": {
              "type": "string"
            }
          }
        },
        "status": {
          "type": "string",
          "description": "Current status of the order line.",
          "readOnly": true
        },
        "currency": {
          "$ref": "#/$defs/CurrencyReference"
        },
        "receiving-warehouse": {
          "type": ["object", "null"],
          "description": "Receiving warehouse reference.",
          "properties": {
            "id": {
              "type": "integer"
            },
            "name": {
              "type": "string"
            }
          }
        },
        "created-at": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp when the line was created.",
          "readOnly": true
        },
        "updated-at": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp when the line was last updated.",
          "readOnly": true
        }
      },
      "required": [
        "description",
        "quantity",
        "price"
      ]
    },
    "AttachmentReference": {
      "type": "object",
      "description": "Reference to a file attachment.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Coupa unique identifier for the attachment."
        },
        "file-name": {
          "type": "string",
          "description": "Name of the attached file."
        },
        "file-url": {
          "type": "string",
          "format": "uri",
          "description": "URL to download the attachment."
        }
      }
    },
    "MilestoneReference": {
      "type": "object",
      "description": "Reference to a procurement milestone.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Coupa unique identifier for the milestone."
        },
        "name": {
          "type": "string",
          "description": "Milestone name."
        }
      }
    }
  },
  "examples": [
    {
      "id": 1,
      "po-number": "PO-2024-001",
      "status": "issued",
      "type": "ExternalOrderHeader",
      "version": 1,
      "internal-revision": 1,
      "acknowledged-flag": false,
      "total": 5000.00,
      "currency": {
        "id": 1,
        "code": "USD"
      },
      "supplier": {
        "id": 42,
        "name": "Acme Office Supplies",
        "number": "SUP-001"
      },
      "requester": {
        "id": 10,
        "login": "jsmith",
        "email": "jsmith@example.com"
      },
      "ship-to-address": {
        "id": 5,
        "name": "Main Office",
        "street1": "123 Business Ave",
        "city": "San Francisco",
        "state": "CA",
        "postal-code": "94105",
        "country": {
          "id": 1,
          "code": "US"
        }
      },
      "payment-term": {
        "id": 1,
        "code": "Net 30"
      },
      "payment-method": "invoice",
      "order-lines": [
        {
          "id": 101,
          "line-num": 1,
          "description": "Office Desk Chair - Ergonomic",
          "quantity": 10,
          "price": 500.00,
          "total": 5000.00,
          "uom": {
            "id": 1,
            "code": "EA"
          },
          "need-by-date": "2024-04-15T00:00:00+00:00",
          "source-part-num": "CHAIR-ERG-001"
        }
      ],
      "exported": false,
      "invoice-stop": false,
      "hide-price": false,
      "created-at": "2024-03-01T10:30:00+00:00",
      "updated-at": "2024-03-01T10:30:00+00:00"
    }
  ]
}