docs.vin

invoice

The invoice noun — identity, lifecycle, events, and every capability as an anchored section: 10 capabilities, 0 live, 10 sandbox, 0 declared.

invoice is one of the estate's 317 automotive nouns — a job a car needs done. It carries 10 capabilities: 0 live, 10 sandbox, 0 declared · doors payments.vin · aggregator.vin.

Identity

Nouninvoice
PillarCommerce (facets: 3 data · 3 services · 4 commerce)
Capabilities10 — 0 live · 10 sandbox · 0 declared
EntitiesInvoice
Doorsaggregator.vin · payments.vin
SDKVin.invoice.* from apis.vin
Address/catalog/invoice#{action} — the anchor IS the wire name minus invoice.

Lifecycle

Invoice — InvoiceFSM: 5 states, 6 transitions — Created · Issued · PartiallyPaid · Paid · Void. Each transition is a past-tense event on the record.

Events

The vocabulary this noun can append to the record — 10 past-tense, versioned event types, each linked to the capability that emits it:

Discover & read

status

invoice.status · GET /invoices/status · gate none · sandbox · answers InvoiceStatus@1

FieldTypeRequiredNotes
vinstringno—

Door — payments.vin serves this noun on its two routes: / (the landing) · /KNDRKDJG4S5286364 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

the SDK — invoice.status
import { invoice } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await invoice.status({"vin":"KNDRKDJG4S5286364"})
GET /invoices/status
curl 'https://apis.vin/invoices/status?vin=KNDRKDJG4S5286364'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-17T12:42:12.985Z · HTTP 200
{
  "type": "OK",
  "answers": "InvoiceStatus@1",
  "value": {
    "invoice": {
      "$type": "Invoice",
      "$id": "invoice_in_1",
      "number": "INV-00001",
      "reference": "KNDRKDJG4S5286364",
      "payerRef": "payer-sandbox",
      "status": "open",
      "lineItems": [
        {
          "description": "Vehicle sale",
          "quantity": 1,
          "unitAmount": {
            "amount": "3150000",
            "currency": "USD"
          },
          "amount": {
            "amount": "3150000",
            "currency": "USD"
          }
        }
      ],
      "total": {
        "amount": "3150000",
        "currency": "USD"
      },
      "dueAt": "2026-09-09T00:00:00.000Z",
      "hostedUrl": "https://invoice.invoicing-rail.sandbox/in_1",
      "createdAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "in_1"
      }
    }
  },
  "evidence": {
    "invoice": {
      "$type": "Invoice",
      "$id": "invoice_in_1",
      "number": "INV-00001",
      "reference": "KNDRKDJG4S5286364",
      "payerRef": "payer-sandbox",
      "status": "open",
      "lineItems": [
        {
          "description": "Vehicle sale",
          "quantity": 1,
          "unitAmount": {
            "amount": "3150000",
            "currency": "USD"
          },
          "amount": {
            "amount": "3150000",
            "currency": "USD"
          }
        }
      ],
      "total": {
        "amount": "3150000",
        "currency": "USD"
      },
      "dueAt": "2026-09-09T00:00:00.000Z",
      "hostedUrl": "https://invoice.invoicing-rail.sandbox/in_1",
      "createdAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "in_1"
      }
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "invoicing-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

Pay & settle

pay

invoice.pay · POST /invoices/pay · gate offer · sandbox · answers InvoicePay@1

FieldTypeRequiredNotes
vinstringno—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — payments.vin serves this noun on its two routes: / (the landing) · /KNDRKDJG4S5286364 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

Emits — Invoice.failed@1 · Invoice.paid@1 · Invoice.partiallyPaid@1.

the SDK — invoice.pay
import { invoice } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await invoice.pay({"vin":"KNDRKDJG4S5286364"})
POST /invoices/pay
curl -X POST https://apis.vin/invoices/pay \
  -H 'content-type: application/json' \
  -d '{"vin":"KNDRKDJG4S5286364"}'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-17T12:42:12.978Z · HTTP 200
{
  "type": "OK",
  "answers": "InvoicePay@1",
  "value": {
    "payment": {
      "$type": "InvoicePayment",
      "$id": "invoicepayment_pay_1",
      "invoiceId": "invoice_in_1",
      "amount": {
        "amount": "3150000",
        "currency": "USD"
      },
      "status": "paid",
      "scheme": "card",
      "paidAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "pay_1"
      }
    }
  },
  "evidence": {
    "payment": {
      "$type": "InvoicePayment",
      "$id": "invoicepayment_pay_1",
      "invoiceId": "invoice_in_1",
      "amount": {
        "amount": "3150000",
        "currency": "USD"
      },
      "status": "paid",
      "scheme": "card",
      "paidAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "pay_1"
      }
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "invoicing-rail-sandbox"
  },
  "events": [
    "Invoice.paid@1"
  ],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

dealerInvoice

invoice.dealerInvoice · GET /invoices/dealer-invoice · gate key · sandbox · answers InvoiceDealerInvoice@1

FieldTypeRequiredNotes
vinstringno—

Door — payments.vin serves this noun on its two routes: / (the landing) · /KNDRKDJG4S5286364 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

the SDK — invoice.dealerInvoice
import { invoice } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await invoice.dealerInvoice({"vin":"KNDRKDJG4S5286364"})
GET /invoices/dealer-invoice
curl 'https://apis.vin/invoices/dealer-invoice?vin=KNDRKDJG4S5286364'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-17T12:42:12.974Z · HTTP 200
{
  "type": "OK",
  "answers": "InvoiceDealerInvoice@1",
  "value": {
    "invoice": {
      "$type": "Invoice",
      "$id": "invoice_in_1",
      "number": "INV-00001",
      "reference": "KNDRKDJG4S5286364",
      "payerRef": "payer-sandbox",
      "status": "open",
      "lineItems": [
        {
          "description": "Vehicle (dealer cost)",
          "quantity": 1,
          "unitAmount": {
            "amount": "2980000",
            "currency": "USD"
          },
          "amount": {
            "amount": "2980000",
            "currency": "USD"
          }
        },
        {
          "description": "Destination freight",
          "quantity": 1,
          "unitAmount": {
            "amount": "119500",
            "currency": "USD"
          },
          "amount": {
            "amount": "119500",
            "currency": "USD"
          }
        }
      ],
      "total": {
        "amount": "3099500",
        "currency": "USD"
      },
      "dueAt": "2026-09-09T00:00:00.000Z",
      "hostedUrl": "https://invoice.invoicing-rail.sandbox/in_1",
      "createdAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "in_1"
      }
    }
  },
  "evidence": {
    "invoice": {
      "$type": "Invoice",
      "$id": "invoice_in_1",
      "number": "INV-00001",
      "reference": "KNDRKDJG4S5286364",
      "payerRef": "payer-sandbox",
      "status": "open",
      "lineItems": [
        {
          "description": "Vehicle (dealer cost)",
          "quantity": 1,
          "unitAmount": {
            "amount": "2980000",
            "currency": "USD"
          },
          "amount": {
            "amount": "2980000",
            "currency": "USD"
          }
        },
        {
          "description": "Destination freight",
          "quantity": 1,
          "unitAmount": {
            "amount": "119500",
            "currency": "USD"
          },
          "amount": {
            "amount": "119500",
            "currency": "USD"
          }
        }
      ],
      "total": {
        "amount": "3099500",
        "currency": "USD"
      },
      "dueAt": "2026-09-09T00:00:00.000Z",
      "hostedUrl": "https://invoice.invoicing-rail.sandbox/in_1",
      "createdAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "in_1"
      }
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "invoicing-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

Fulfill & operate

generate

invoice.generate · POST /invoices/generate · gate offer · sandbox · answers InvoiceGenerate@1

FieldTypeRequiredNotes
vinstringno—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — payments.vin serves this noun on its two routes: / (the landing) · /KNDRKDJG4S5286364 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

Emits — Invoice.generated@1.

the SDK — invoice.generate
import { invoice } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await invoice.generate({"vin":"KNDRKDJG4S5286364"})
POST /invoices/generate
curl -X POST https://apis.vin/invoices/generate \
  -H 'content-type: application/json' \
  -d '{"vin":"KNDRKDJG4S5286364"}'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-17T12:42:12.974Z · HTTP 200
{
  "type": "OK",
  "answers": "InvoiceGenerate@1",
  "value": {
    "invoice": {
      "$type": "Invoice",
      "$id": "invoice_in_1",
      "number": "INV-00001",
      "reference": "KNDRKDJG4S5286364",
      "payerRef": "payer-sandbox",
      "status": "open",
      "lineItems": [
        {
          "description": "Vehicle sale",
          "quantity": 1,
          "unitAmount": {
            "amount": "3150000",
            "currency": "USD"
          },
          "amount": {
            "amount": "3150000",
            "currency": "USD"
          }
        }
      ],
      "total": {
        "amount": "3150000",
        "currency": "USD"
      },
      "dueAt": "2026-09-09T00:00:00.000Z",
      "hostedUrl": "https://invoice.invoicing-rail.sandbox/in_1",
      "createdAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "in_1"
      }
    }
  },
  "evidence": {
    "invoice": {
      "$type": "Invoice",
      "$id": "invoice_in_1",
      "number": "INV-00001",
      "reference": "KNDRKDJG4S5286364",
      "payerRef": "payer-sandbox",
      "status": "open",
      "lineItems": [
        {
          "description": "Vehicle sale",
          "quantity": 1,
          "unitAmount": {
            "amount": "3150000",
            "currency": "USD"
          },
          "amount": {
            "amount": "3150000",
            "currency": "USD"
          }
        }
      ],
      "total": {
        "amount": "3150000",
        "currency": "USD"
      },
      "dueAt": "2026-09-09T00:00:00.000Z",
      "hostedUrl": "https://invoice.invoicing-rail.sandbox/in_1",
      "createdAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "in_1"
      }
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "invoicing-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

issue

invoice.issue · POST /invoices/issue · gate key · sandbox · answers Invoice@1

FieldTypeRequiredNotes
lineItemsarray<object>yes—
payerstringyes—
subjectstringno—
deliverarray<string>no—

Door — payments.vin serves this noun on its two routes: / (the landing) · /KNDRKDJG4S5286364 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

Emits — Invoice.created@1 · Invoice.paid@1 · Invoice.voided@1.

the SDK — invoice.issue
import { invoice } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await invoice.issue({"lineItems":[],"payer":"payer"})
POST /invoices/issue
curl -X POST https://apis.vin/invoices/issue \
  -H 'content-type: application/json' \
  -d '{"lineItems":[],"payer":"payer"}'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-16T14:50:09.886Z · HTTP 200
{
  "type": "OK",
  "answers": "Invoice@1",
  "value": {
    "invoice": {
      "$type": "Invoice",
      "$id": "invoice_in_1",
      "number": "INV-00001",
      "reference": "magic-clear",
      "payerRef": "payer-sandbox",
      "status": "open",
      "lineItems": [
        {
          "description": "Vehicle sale",
          "quantity": 1,
          "unitAmount": {
            "amount": "3150000",
            "currency": "USD"
          },
          "amount": {
            "amount": "3150000",
            "currency": "USD"
          }
        }
      ],
      "total": {
        "amount": "3150000",
        "currency": "USD"
      },
      "dueAt": "2026-09-09T00:00:00.000Z",
      "hostedUrl": "https://invoice.invoicing-rail.sandbox/in_1",
      "createdAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "in_1"
      }
    }
  },
  "evidence": {
    "invoice": {
      "$type": "Invoice",
      "$id": "invoice_in_1",
      "number": "INV-00001",
      "reference": "magic-clear",
      "payerRef": "payer-sandbox",
      "status": "open",
      "lineItems": [
        {
          "description": "Vehicle sale",
          "quantity": 1,
          "unitAmount": {
            "amount": "3150000",
            "currency": "USD"
          },
          "amount": {
            "amount": "3150000",
            "currency": "USD"
          }
        }
      ],
      "total": {
        "amount": "3150000",
        "currency": "USD"
      },
      "dueAt": "2026-09-09T00:00:00.000Z",
      "hostedUrl": "https://invoice.invoicing-rail.sandbox/in_1",
      "createdAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "in_1"
      }
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "invoicing-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

send

invoice.send · POST /invoices/send · gate offer · sandbox · answers InvoiceSend@1

FieldTypeRequiredNotes
vinstringno—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — payments.vin serves this noun on its two routes: / (the landing) · /KNDRKDJG4S5286364 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

Emits — Invoice.requested@1 · Invoice.sent@1.

the SDK — invoice.send
import { invoice } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await invoice.send({"vin":"KNDRKDJG4S5286364"})
POST /invoices/send
curl -X POST https://apis.vin/invoices/send \
  -H 'content-type: application/json' \
  -d '{"vin":"KNDRKDJG4S5286364"}'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-17T12:42:12.978Z · HTTP 200
{
  "type": "OK",
  "answers": "InvoiceSend@1",
  "value": {
    "invoice": {
      "$type": "Invoice",
      "$id": "invoice_in_1",
      "number": "INV-00001",
      "reference": "KNDRKDJG4S5286364",
      "payerRef": "payer-sandbox",
      "status": "open",
      "lineItems": [
        {
          "description": "Vehicle sale",
          "quantity": 1,
          "unitAmount": {
            "amount": "3150000",
            "currency": "USD"
          },
          "amount": {
            "amount": "3150000",
            "currency": "USD"
          }
        }
      ],
      "total": {
        "amount": "3150000",
        "currency": "USD"
      },
      "dueAt": "2026-09-09T00:00:00.000Z",
      "hostedUrl": "https://invoice.invoicing-rail.sandbox/in_1",
      "createdAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "in_1"
      }
    }
  },
  "evidence": {
    "invoice": {
      "$type": "Invoice",
      "$id": "invoice_in_1",
      "number": "INV-00001",
      "reference": "KNDRKDJG4S5286364",
      "payerRef": "payer-sandbox",
      "status": "open",
      "lineItems": [
        {
          "description": "Vehicle sale",
          "quantity": 1,
          "unitAmount": {
            "amount": "3150000",
            "currency": "USD"
          },
          "amount": {
            "amount": "3150000",
            "currency": "USD"
          }
        }
      ],
      "total": {
        "amount": "3150000",
        "currency": "USD"
      },
      "dueAt": "2026-09-09T00:00:00.000Z",
      "hostedUrl": "https://invoice.invoicing-rail.sandbox/in_1",
      "createdAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "in_1"
      }
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "invoicing-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

Lifecycle & state

void

invoice.void · POST /invoices/void · gate offer · sandbox · answers InvoiceVoid@1

FieldTypeRequiredNotes
vinstringno—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — payments.vin serves this noun on its two routes: / (the landing) · /KNDRKDJG4S5286364 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

Emits — Invoice.voided@1.

the SDK — invoice.void
import { invoice } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await invoice.void({"vin":"KNDRKDJG4S5286364"})
POST /invoices/void
curl -X POST https://apis.vin/invoices/void \
  -H 'content-type: application/json' \
  -d '{"vin":"KNDRKDJG4S5286364"}'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-17T12:42:12.993Z · HTTP 200
{
  "type": "OK",
  "answers": "InvoiceVoid@1",
  "value": {
    "invoice": {
      "$type": "Invoice",
      "$id": "invoice_in_1",
      "number": "INV-00001",
      "reference": "KNDRKDJG4S5286364",
      "payerRef": "payer-sandbox",
      "status": "void",
      "lineItems": [
        {
          "description": "Vehicle sale",
          "quantity": 1,
          "unitAmount": {
            "amount": "3150000",
            "currency": "USD"
          },
          "amount": {
            "amount": "3150000",
            "currency": "USD"
          }
        }
      ],
      "total": {
        "amount": "3150000",
        "currency": "USD"
      },
      "dueAt": "2026-09-09T00:00:00.000Z",
      "hostedUrl": "https://invoice.invoicing-rail.sandbox/in_1",
      "createdAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "in_1"
      }
    }
  },
  "evidence": {
    "invoice": {
      "$type": "Invoice",
      "$id": "invoice_in_1",
      "number": "INV-00001",
      "reference": "KNDRKDJG4S5286364",
      "payerRef": "payer-sandbox",
      "status": "void",
      "lineItems": [
        {
          "description": "Vehicle sale",
          "quantity": 1,
          "unitAmount": {
            "amount": "3150000",
            "currency": "USD"
          },
          "amount": {
            "amount": "3150000",
            "currency": "USD"
          }
        }
      ],
      "total": {
        "amount": "3150000",
        "currency": "USD"
      },
      "dueAt": "2026-09-09T00:00:00.000Z",
      "hostedUrl": "https://invoice.invoicing-rail.sandbox/in_1",
      "createdAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "in_1"
      }
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "invoicing-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

More actions

credit

invoice.credit · POST /invoices/credit · gate offer · sandbox · answers InvoiceCredit@1

FieldTypeRequiredNotes
vinstringno—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — payments.vin serves this noun on its two routes: / (the landing) · /KNDRKDJG4S5286364 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

Emits — Invoice.creditMemoed@1 · Invoice.failed@1.

the SDK — invoice.credit
import { invoice } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await invoice.credit({"vin":"KNDRKDJG4S5286364"})
POST /invoices/credit
curl -X POST https://apis.vin/invoices/credit \
  -H 'content-type: application/json' \
  -d '{"vin":"KNDRKDJG4S5286364"}'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-17T12:42:12.974Z · HTTP 200
{
  "type": "OK",
  "answers": "InvoiceCredit@1",
  "value": {
    "vin": "KNDRKDJG4S5286364",
    "noun": "invoice",
    "asOf": "2026-08-10",
    "id": "FIN-62411566",
    "subjectId": "DL-4cdc9c7d",
    "lineItems": [
      {
        "kind": "doc-fee",
        "amountCents": 8500,
        "basis": "posted-doc-fee"
      },
      {
        "kind": "title-reg",
        "amountCents": 19000,
        "basis": "title-rail-posted-total"
      },
      {
        "kind": "sales-tax",
        "amountCents": 189750,
        "basis": "posted-rate-on-asking-value"
      }
    ],
    "amount": 217250,
    "status": "Created",
    "creditMemo": {
      "invoiceId": "FIN-62411566",
      "kind": "doc-fee",
      "amountCents": 8500,
      "currency": "USD",
      "statutoryFees": "never-credited",
      "status": "not-yet-issued"
    }
  },
  "evidence": {
    "vin": "KNDRKDJG4S5286364",
    "noun": "invoice",
    "asOf": "2026-08-10",
    "id": "FIN-62411566",
    "subjectId": "DL-4cdc9c7d",
    "lineItems": [
      {
        "kind": "doc-fee",
        "amountCents": 8500,
        "basis": "posted-doc-fee"
      },
      {
        "kind": "title-reg",
        "amountCents": 19000,
        "basis": "title-rail-posted-total"
      },
      {
        "kind": "sales-tax",
        "amountCents": 189750,
        "basis": "posted-rate-on-asking-value"
      }
    ],
    "amount": 217250,
    "status": "Created",
    "creditMemo": {
      "invoiceId": "FIN-62411566",
      "kind": "doc-fee",
      "amountCents": 8500,
      "currency": "USD",
      "statutoryFees": "never-credited",
      "status": "not-yet-issued"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "billing-annex-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

factor

invoice.factor · POST /invoices/factor · gate key · sandbox · answers InvoiceFactor@1

No input — this capability takes no request body.

Door — aggregator.vin serves this noun on its two routes: / (the landing) · /KNDRKDJG4S5286364 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

Emits — Invoice.factored@1.

the SDK — invoice.factor
import { invoice } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await invoice.factor()
POST /invoices/factor
curl -X POST https://apis.vin/invoices/factor \
  -H 'content-type: application/json' \
  -d '{}'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-16T14:50:09.886Z · HTTP 200
{
  "type": "OK",
  "answers": "InvoiceFactor@1",
  "value": {
    "vin": "1HGCM82633A004352",
    "noun": "invoice",
    "asOf": "2026-08-10",
    "invoice": {
      "status": "no-invoice-on-file"
    },
    "factoring": {
      "status": "no-invoice-on-file"
    }
  },
  "evidence": {
    "vin": "1HGCM82633A004352",
    "noun": "invoice",
    "asOf": "2026-08-10",
    "invoice": {
      "status": "no-invoice-on-file"
    },
    "factoring": {
      "status": "no-invoice-on-file"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "billing-annex-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

lineItems

invoice.lineItems · GET /invoices/line-items · gate key · sandbox · answers InvoiceLineItems@1

FieldTypeRequiredNotes
vinstringno—

Door — payments.vin serves this noun on its two routes: / (the landing) · /KNDRKDJG4S5286364 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

the SDK — invoice.lineItems
import { invoice } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await invoice.lineItems({"vin":"KNDRKDJG4S5286364"})
GET /invoices/line-items
curl 'https://apis.vin/invoices/line-items?vin=KNDRKDJG4S5286364'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-17T12:42:12.975Z · HTTP 200
{
  "type": "OK",
  "answers": "InvoiceLineItems@1",
  "value": {
    "invoice": {
      "$type": "Invoice",
      "$id": "invoice_in_1",
      "number": "INV-00001",
      "reference": "KNDRKDJG4S5286364",
      "payerRef": "payer-sandbox",
      "status": "open",
      "lineItems": [
        {
          "description": "Vehicle",
          "quantity": 1,
          "unitAmount": {
            "amount": "3150000",
            "currency": "USD"
          },
          "amount": {
            "amount": "3150000",
            "currency": "USD"
          }
        },
        {
          "description": "Documentation fee",
          "quantity": 1,
          "unitAmount": {
            "amount": "69900",
            "currency": "USD"
          },
          "amount": {
            "amount": "69900",
            "currency": "USD"
          }
        }
      ],
      "total": {
        "amount": "3219900",
        "currency": "USD"
      },
      "dueAt": "2026-09-09T00:00:00.000Z",
      "hostedUrl": "https://invoice.invoicing-rail.sandbox/in_1",
      "createdAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "in_1"
      }
    }
  },
  "evidence": {
    "invoice": {
      "$type": "Invoice",
      "$id": "invoice_in_1",
      "number": "INV-00001",
      "reference": "KNDRKDJG4S5286364",
      "payerRef": "payer-sandbox",
      "status": "open",
      "lineItems": [
        {
          "description": "Vehicle",
          "quantity": 1,
          "unitAmount": {
            "amount": "3150000",
            "currency": "USD"
          },
          "amount": {
            "amount": "3150000",
            "currency": "USD"
          }
        },
        {
          "description": "Documentation fee",
          "quantity": 1,
          "unitAmount": {
            "amount": "69900",
            "currency": "USD"
          },
          "amount": {
            "amount": "69900",
            "currency": "USD"
          }
        }
      ],
      "total": {
        "amount": "3219900",
        "currency": "USD"
      },
      "dueAt": "2026-09-09T00:00:00.000Z",
      "hostedUrl": "https://invoice.invoicing-rail.sandbox/in_1",
      "createdAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "invoicing-rail"
      },
      "providerData": {
        "externalId": "in_1"
      }
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "invoicing-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

Data model

The record shape behind this noun — one entity, each property an evidence field. See the whole estate model on the data model page.

Invoice

Schema

PropertyTypeNotes
ididinv_
subjectIdref→Deal|ServiceOrder—
lineItemsLineItem[]—
amountmoney—
statusInvoiceFSM—

Relationships

FromToCardinalityAs
invoicepayment1:0..*paid by

Modeled

The noun drawn out — its record shape, its lifecycle, and how it is exercised end to end. 2 diagrams, rendered from the estate model.

Invoice · Class model

Invoice · State machine

Generated from the catalog. Every capability, answer, gate, and entity on this page is a rendered descriptor — it cannot drift from the wire.

insurance

The insurance noun — identity, lifecycle, events, and every capability as an anchored section: 28 capabilities, 0 live, 28 sandbox, 0 declared.

mandate

The mandate noun — identity, lifecycle, events, and every capability as an anchored section: 8 capabilities, 0 live, 8 sandbox, 0 declared.

On this page

Identity
Lifecycle
Events
Discover & read
status
Pay & settle
pay
dealerInvoice
Fulfill & operate
generate
issue
send
Lifecycle & state
void
More actions
credit
factor
lineItems
Data model
Invoice
Modeled