Invoices

Create an invoice#

Authentication: Bearer key · Required scope: invoices.write

Returns 201 for a new invoice, or 200 for an exact replay. Save billing details first; otherwise the response is 409 billing_details_required.

Choose amountUsd, or the complete chainId + token + amount set. Do not send both pricing forms. Store and profile token switches apply.

import { Forwend } from "forwend";

const forwend = new Forwend({
  apiKey: process.env.FORWEND_KEY!,
  profileId: process.env.FORWEND_PROFILE_ID!,
  baseUrl: process.env.FORWEND_API_URL!,
});

const invoice = await forwend.invoices.create(
  { amountUsd: "1250.00", metadata: { order_id: "1042" } },
  { idempotencyKey: "order-1042" },
);
const latest = await forwend.invoices.get(invoice.invoiceId);

Request headers#

Create request body#

Read an invoice#

Authentication: Bearer key · Required scope: invoices.read

Returns 200 with the invoice detail. No request body. An unknown or inaccessible invoice returns 404 invoice_not_found.

List invoices#

Authentication: Bearer key · Required scope: invoices.read

Returns 200 with {items, nextCursor}, newest first. nextCursor is null on the last page. No request body.

Invoice response#

Responses can add fields. Ignore unknown fields and read paymentStatus independently from settlementStatus.

Create conflicts include 409 idempotency_conflict and billing_details_required. Invalid JSON or headers return 400 malformed_request.

Errors#

Responses use {error: {code, message}}. Missing or invalid credentials return 401; missing scope or a different profile returns 403. Objects outside the caller’s store or mode are hidden with 404.

Invalid values return 422 invalid_value. Rate limiting returns 429 rate_limited with Retry-After. A starting network can return 503 network_not_ready; an unexpected server error returns 500 internal.