Create an invoice

Creates a new payment invoice in the Triport console billing flow. The billing surface uses a per-rail model: each invoice is bound to exactly one channel, one rail, and one freshly derived deposit address. To offer the customer a choice of payment methods, create one invoice per method.

The invoice is created in pending status with an expiry timestamp. The response includes the deposit address, a wallet-ready qr_uri, and the running payments_received_micro total (0 at creation). Watch the invoice through to settlement over the SSE stream at GET /v1/billing/invoices/{id}/events, or pay it from the user's internal balance with POST /v1/billing/invoices/{id}/pay-from-balance.

This endpoint requires an authenticated console session — anonymous invoices are rejected, because a per-rail invoice drives subscription activation and must be attributed to a user. The set of valid rail values and their channel compatibility comes from GET /v1/billing/rails (unauthenticated); build your rail selector from that list so you never submit an unsupported combination.

Send a JSON request body. No path or query parameters.

201 Created:

Errors use the shared {"error": "<code>"} envelope.

See Errors for the shared error envelope and conventions.

JavaScript (fetch)

const res = await fetch("https://api.triport.io/v1/billing/invoices", {
  method: "POST",
  credentials: "include", // send the console session cookie
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    channel: "crypto-onchain",
    rail: "sol-spl-usdc",
    bill_action: { type: "subscription_purchase", plan: "starter", months: 1 },
    description: "Starter plan — 1 month",
    ttl_seconds: 1800,
    client_request_id: crypto.randomUUID(),
  }),
});


if (!res.ok) {
  const { error } = await res.json();
  throw new Error(error);
}
const invoice = await res.json();
console.log(invoice.address.address, invoice.qr_uri);

TypeScript SDK (@triport/sdk)

import { Triport } from "@triport/sdk";


// Console client: authenticates with the browser session cookie.
const client = new Triport({ session: true });


const invoice = await client.billing.createInvoice({
  channel: "crypto-onchain",
  rail: "sol-spl-usdc",
  billAction: { type: "subscription_purchase", plan: "starter", months: 1 },
  description: "Starter plan — 1 month",
  ttlSeconds: 1800,
  clientRequestId: crypto.randomUUID(),
});


console.log(invoice.status, invoice.address?.address);

Python (triport-sdk)

import os
import uuid
from triport import Triport


# Console client authenticates with the session cookie.
client = Triport(session_cookie=os.environ["TRIPORT_SESSION"])


invoice = client.billing.create_invoice(
    channel="crypto-onchain",
    rail="sol-spl-usdc",
    bill_action={"type": "subscription_purchase", "plan": "starter", "months": 1},
    description="Starter plan — 1 month",
    ttl_seconds=1800,
    client_request_id=str(uuid.uuid4()),
)


print(invoice["status"], invoice["address"]["address"])

• One invoice = one rail. To present multiple payment options, create one invoice per rail and let the customer pick. Discover valid rail/channel combinations from GET /v1/billing/rails (no auth required) and build your selector from channels / supports_inapp / fx_rate_required.
• Let the backend price it. Omit amount_micro (or send 0) to have the pricing resolver compute the charge from bill_action. Pass an explicit amount_micro only when you must override.
• Idempotency. Always set client_request_id (a UUID v4) so a retried POST returns the same invoice instead of creating a duplicate.
• FX rates. Stablecoin rails (*-usdc, *-usdt) generally price 1:1 and do not take an FX rate; native-token rails such as sol-native require fx_rate_micro_per_atomic. The rails list's fx_rate_required flag tells you which is which — supplying the wrong thing yields a 400.
• In-app channel. For channel: "crypto-inapp", after creating the invoice build and relay the wallet transaction via POST /v1/billing/invoices/{id}/inapp/build and .../inapp/submit.
• Track settlement. Subscribe to GET /v1/billing/invoices/{id}/events (SSE) for invoice_paid / invoice_progress / invoice_expired_sweep updates, or settle immediately from the user's balance with POST /v1/billing/invoices/{id}/pay-from-balance.