---
title: "Create an invoice"
method: POST
path: "/invoices"
tags: ["Invoices"]
---

# Create an invoice

`POST /invoices`

## Request

- Base URL: `https://shieldz.cash/api/v1`
- URL: `https://shieldz.cash/api/v1/invoices`
- Auth: HTTP bearer

## Request body

- InvoiceCreate: Send amount_usd_cents, or line_items and the total is computed from them.
  - `amount_usd_cents` integer: Amount in USD cents. Omit when sending line_items.
  - `line_items` object[]
    - `price` string: A price ID (price_…) from your catalog.
    - `price_data` object: An inline price, for items not in your catalog.
      - `name` string, required
      - `unit_amount_usd_cents` integer, required
    - `quantity` integer
    - `amount_usd_cents` integer: Only for a price where the customer chooses the amount.
  - `client_reference_id` string: Your order or cart id, echoed on the invoice and webhooks.
  - `return_url` string, uri: Public https URL the paid checkout returns the buyer to. success_url is accepted as an alias.
  - `memo` string
  - `customer_email` string, email
  - `expires_in_seconds` integer
  - `idempotency_key` string: Replaying the same key returns the original invoice.
  - `metadata` object: Arbitrary JSON, echoed back on webhooks.
  - `settlement` Settlement
    - `chain` string
    - `asset` string
    - `address` string

## Response `201`

Created

- Invoice
  - `id` string
  - `object` 'invoice'
  - `amount_usd_cents` integer
  - `memo` string, nullable
  - `settlement` Settlement
    - `chain` string
    - `asset` string
    - `address` string
  - `status` 'pending' | 'paid' | 'expired' | 'failed'
  - `pay_url` string, uri
  - `expires_at` integer: Unix milliseconds.
  - `paid_at` integer, nullable
  - `mode` 'live' | 'test'
  - `metadata` unknown
  - `line_items` LineItem[], nullable
    - `price` string, nullable: The catalog price (price_…); null for inline price_data.
    - `product` string, nullable: The catalog product (prod_…); null for inline price_data.
    - `name` string: Product name at the time of purchase.
    - `quantity` integer
    - `unit_amount_usd_cents` integer: Price per unit charged, in USD cents.
    - `amount_usd_cents` integer: unit_amount_usd_cents × quantity.
  - `payment_link` string, nullable: The payment link this invoice came from.
  - `shipping` object, nullable: Shipping address from the payment link page. Only returned to the shop (its API key or dashboard).
    - `name` string
    - `line1` string
    - `line2` string
    - `city` string
    - `state` string
    - `postal_code` string
    - `country` string
  - `client_reference_id` string, nullable

## Other responses

- `400`: Error
- `401`: Error

---

[API](https://skmtc.dev/shieldz/apis/shieldz-api.md) · [All operations](https://skmtc.dev/shieldz/apis/shieldz-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shieldz/apis/shieldz-api/revisions/0d7156bee439?raw)