# Stripe Invoice

> Stripe Invoice with amounts, payment status, and billing period tracking.

- Name: `stripe-invoice`
- Categories: stripe
- Depends on: `@open-types/stripe-shared`
- Detail page: https://open-types.dev/types/stripe-invoice

## Install

```bash
# Types only
npx shadcn add @open-types/stripe-invoice

# Types + Zod v4 validators
npx shadcn add @open-types/stripe-invoice-zod

# Types + real-world examples
npx shadcn add @open-types/stripe-invoice-examples
```

## Types

```typescript
import type { StripeMetadata } from "./stripe-shared";

export type StripeInvoiceStatus = "draft" | "open" | "paid" | "uncollectible" | "void";

export interface StripeInvoice {
  id: string;
  object: "invoice";
  customer: string | null;
  subscription: string | null;
  status: StripeInvoiceStatus | null;
  amount_due: number;
  amount_paid: number;
  amount_remaining: number;
  currency: string;
  due_date: number | null;
  paid: boolean;
  period_start: number;
  period_end: number;
  hosted_invoice_url: string | null;
  invoice_pdf: string | null;
  metadata: StripeMetadata;
  created: number;
  livemode: boolean;
}
```

## Zod validator

```typescript
import * as z from "zod";
import type { StripeInvoice, StripeInvoiceStatus } from "../types/stripe-invoice";
import { stripeMetadataSchema } from "./stripe-shared";

export const stripeInvoiceStatusSchema = z.enum([
  "draft",
  "open",
  "paid",
  "uncollectible",
  "void",
]) satisfies z.ZodType<StripeInvoiceStatus>;

export const stripeInvoiceSchema = z.object({
  id: z.string(),
  object: z.literal("invoice"),
  customer: z.string().nullable(),
  subscription: z.string().nullable(),
  status: stripeInvoiceStatusSchema.nullable(),
  amount_due: z.number(),
  amount_paid: z.number(),
  amount_remaining: z.number(),
  currency: z.string(),
  due_date: z.number().nullable(),
  paid: z.boolean(),
  period_start: z.number(),
  period_end: z.number(),
  hosted_invoice_url: z.string().nullable(),
  invoice_pdf: z.string().nullable(),
  metadata: stripeMetadataSchema,
  created: z.number(),
  livemode: z.boolean(),
}) satisfies z.ZodType<StripeInvoice>;

export type { StripeInvoice, StripeInvoiceStatus } from "../types/stripe-invoice";
```

## Examples

```typescript
// Source: https://docs.stripe.com/api/invoices/object
// Captured: 2026-05
import type {
  StripeInvoice,
  StripeInvoiceStatus,
} from "../types/stripe-invoice";
import { stripeIds } from "./shared/stripe.examples";

const open = {
  id: stripeIds.invoice,
  object: "invoice",
  customer: stripeIds.customer,
  subscription: stripeIds.subscription,
  status: "open",
  amount_due: 2500,
  amount_paid: 0,
  amount_remaining: 2500,
  currency: "usd",
  due_date: 1713034800,
  paid: false,
  period_start: 1712948400,
  period_end: 1715626800,
  hosted_invoice_url: "https://invoice.stripe.com/i/acct_123/test_456",
  invoice_pdf: "https://pay.stripe.com/invoice/acct_123/pdf_456",
  metadata: { billing_cycle: "april-2024" },
  created: 1712948400,
  livemode: false,
} as const satisfies StripeInvoice;

export const stripeInvoiceStatusExamples = {
  draft: "draft",
  open: "open",
  paid: "paid",
  uncollectible: "uncollectible",
  void: "void",
} as const satisfies Record<string, StripeInvoiceStatus>;

export const stripeInvoiceExamples = {
  open,
  paid: {
    ...open,
    id: "in_1Ot8xP2eZvKYlo2Cpaid23456",
    status: "paid",
    amount_paid: 2500,
    amount_remaining: 0,
    paid: true,
    due_date: null,
  } satisfies StripeInvoice,
  draft: {
    ...open,
    id: "in_1Ot8xP2eZvKYlo2Cdraft0001",
    status: "draft",
    hosted_invoice_url: null,
    invoice_pdf: null,
  } satisfies StripeInvoice,
  uncollectible: {
    ...open,
    id: "in_1Ot8xP2eZvKYlo2Cuncl00001",
    status: "uncollectible",
  } satisfies StripeInvoice,
  voided: {
    ...open,
    id: "in_1Ot8xP2eZvKYlo2Cvoid00001",
    status: "void",
    paid: false,
    amount_remaining: 0,
  } satisfies StripeInvoice,
  oneOff: {
    ...open,
    id: "in_1Ot8xP2eZvKYlo2Coneoff001",
    customer: null,
    subscription: null,
    status: null,
  } satisfies StripeInvoice,
} as const;
```