Skip to content
HeyX API

Create Pro-Forma

Required scope: proforma:create

Generates a pro-forma document from an order revision. A pro-forma is an off-ledger preview, not a booked invoice. expectedOrderVersion is the order revision to snapshot; a mismatch is rejected. Generation is idempotent through idempotencyKey: reusing the same key returns the original pro-forma.

Generated Reference
POST /public-api/publicapi.v1.ProForma/CreateProForma

Generates or returns the pro-forma document for an immutable order revision. Idempotent per idempotency_key.

Request CreateProFormaRequest
Response CreateProFormaResponse

CreateProFormaRequest

Field Type Description
order_id string Order to generate the pro-forma for.
expected_order_version int32 Order revision to snapshot into the pro-forma.
idempotency_key string Idempotency key; reusing it returns the original pro-forma.

CreateProFormaResponse

Field Type Description
pro_forma ProForma The created or existing pro-forma.

Related Types

ProForma

Field Type Description
id string Stable pro-forma identifier.
customer_id string Customer the pro-forma belongs to.
order_id string Order the pro-forma was generated from.
order_version int32 Order revision snapshotted into the pro-forma.
status ProFormaStatus Pro-forma lifecycle status.
total_minor int64 Total amount in minor currency units.
currency string ISO 4217 currency code.
lines repeated ProFormaLine Pro-forma line items, in document order.
invoice_id optional string Linked invoice identifier once the pro-forma is converted, when set.
created_at int64 Creation time as unix seconds.
finalized_at optional int64 Finalization time as unix seconds, when finalized.

ProFormaLine

Field Type Description
description string Human-readable line description.
quantity int32 Quantity on this line.
unit_price_minor int64 Unit price in minor currency units.
vat_rate double VAT rate applied to this line as a fraction (for example 0.21 for 21%).

Request

Section titled “Request”
{
  "orderId": "<order-id>",
  "expectedOrderVersion": 2,
  "idempotencyKey": "proforma-order-123-v2"
}

Response

Section titled “Response”
{
  "proForma": {
    "id": "<pro-forma-id>",
    "customerId": "<customer-id>",
    "orderId": "<order-id>",
    "orderVersion": 2,
    "status": "PUBLIC_PRO_FORMA_STATUS_DRAFT",
    "totalMinor": "151200",
    "currency": "EUR",
    "lines": [
      { "description": "Solar panel", "quantity": 8, "unitPriceMinor": "18900", "vatRate": 0.21 }
    ],
    "createdAt": "1737936000"
  }
}
HeyX API