---
title: "Create Invoice"
method: POST
path: "/invoices"
tags: ["invoices"]
---

# Create Invoice

`POST /invoices`

Creates and publishes an invoice backed by a SALE pay order. The recipient is emailed a PDF invoice with a hosted payment link. Pass id to publish an existing draft.

## Headers

- `Authorization-Signature` string, required

## Request body

- CreateInvoiceRequest
  - `id` string
  - `invoice` InvoiceMeta, required
    - `no` string, required
    - `date` string, required
    - `due_date` string
  - `from` InvoiceOrganization, required
    - `name` string, required
    - `email` string, required
    - `phone` string
    - `logo` string
    - `street_address` string
    - `city` string
    - `state` string
    - `zip_code` string
    - `country` string
  - `recipient` InvoiceRecipient, required
    - `name` string, required
    - `email` string, required
    - `phone` string
    - `street_address` string
    - `city` string
    - `state` string
    - `zip_code` string
    - `country` string
  - `items` InvoiceItem[], required
    - `id` string
    - `name` string, required
    - `unitPrice` string, required
    - `quantity` string, required
    - `tax` string
    - `image` string

## Response `201`

Invoice created

- InvoiceResponse
  - `archived_at` string, date-time, nullable
  - `created_at` string, date-time
  - `data` object — Invoice details as provided on create.
    - `from` InvoiceOrganization
      - `name` string, required
      - `email` string, required
      - `phone` string
      - `logo` string
      - `street_address` string
      - `city` string
      - `state` string
      - `zip_code` string
      - `country` string
    - `invoice` InvoiceMeta
      - `no` string, required
      - `date` string, required
      - `due_date` string
    - `items` InvoiceItem[]
      - `id` string
      - `name` string, required
      - `unitPrice` string, required
      - `quantity` string, required
      - `tax` string
      - `image` string
    - `recipient` InvoiceRecipient
      - `name` string, required
      - `email` string, required
      - `phone` string
      - `street_address` string
      - `city` string
      - `state` string
      - `zip_code` string
      - `country` string
  - `id` string
  - `order_id` string — Latest linked pay order id.
  - `orders` OrderResponse[]
    - `id` string, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `organization_id` string, required
    - `mode` 'SALE' | 'DEPOSIT' | 'REFUND' | 'SWAP' | 'FEE_CLAIM', required
    - `status` 'PENDING' | 'EXPIRED' | 'FAILED' | 'AWAITING_PAYMENT' | 'OPTIMISTIC_CONFIRMED' | 'AWAITING_CONFIRMATION' | 'EXECUTING_ORDER' | 'COMPLETED' | 'REFUNDED' | 'PARTIAL_PAYMENT', required
    - `fulfillment` OrderFulfillment, required
      - `asset` Currency
        - `id` string, required
        - `chain_id` 1 | 10 | 56 | 137 | 4663 | 8453 | 42161 | 20000000000001 | 30000000000001 | 30000000000002, required
        - `address` string, nullable
        - `symbol` string, required
        - `name` string
        - `decimals` integer, required
        - `image_uri` string, nullable
        - `chain_image_uri` string, nullable
        - `price_usd` number, nullable
      - `amount` Amount, required
        - `ui` string, required
        - `raw` string, required — A big integer represented as a string to preserve precision
        - `value_usd` number, nullable
      - `fiat_unit` string, nullable
      - `rate_usd` string, nullable
      - `recipient` string, nullable
      - `custom_fee_bps` integer, nullable
      - `swap` OrderSwap
        - `trade_type` 'EXACT_INPUT' | 'EXACT_OUTPUT' — Whether the source or destination amount is fixed.
        - `slippage_bps` integer, nullable
    - `payment` PaymentView
      - `payment_rail` 'CRYPTO' | 'FIAT', required
      - `input` QuoteInput, required
        - `currency` Currency, required
          - `id` string, required
          - `chain_id` 1 | 10 | 56 | 137 | 4663 | 8453 | 42161 | 20000000000001 | 30000000000001 | 30000000000002, required
          - `address` string, nullable
          - `symbol` string, required
          - `name` string
          - `decimals` integer, required
          - `image_uri` string, nullable
          - `chain_image_uri` string, nullable
          - `price_usd` number, nullable
        - `amount` Amount, required
          - `ui` string, required
          - `raw` string, required — A big integer represented as a string to preserve precision
          - `value_usd` number, nullable
        - `balance` Amount
          - `ui` string, required
          - `raw` string, required — A big integer represented as a string to preserve precision
          - `value_usd` number, nullable
        - `breakdown` QuoteBreakdown
          - `total` Amount, required
            - `ui` string, required
            - `raw` string, required — A big integer represented as a string to preserve precision
            - `value_usd` number, nullable
          - `base` Amount, required
            - `ui` string, required
            - `raw` string, required — A big integer represented as a string to preserve precision
            - `value_usd` number, nullable
          - `fees` QuoteFees
            - `total_fee` Amount, required
              - …
            - `protocol_fee` Amount
              - …
            - `custom_fee` Amount
              - …
            - `relayer_fee` Amount
              - …
          - `gas` Amount
            - `ui` string, required
            - `raw` string, required — A big integer represented as a string to preserve precision
            - `value_usd` number, nullable
      - `output` QuoteOutput, required
        - `currency` Currency, required
          - `id` string, required
          - `chain_id` 1 | 10 | 56 | 137 | 4663 | 8453 | 42161 | 20000000000001 | 30000000000001 | 30000000000002, required
          - `address` string, nullable
          - `symbol` string, required
          - `name` string
          - `decimals` integer, required
          - `image_uri` string, nullable
          - `chain_image_uri` string, nullable
          - `price_usd` number, nullable
        - `amount` Amount, required
          - `ui` string, required
          - `raw` string, required — A big integer represented as a string to preserve precision
          - `value_usd` number, nullable
        - `amount_out_minimum` Amount
          - `ui` string, required
          - `raw` string, required — A big integer represented as a string to preserve precision
          - `value_usd` number, nullable
      - `funding` PaymentFunding
        - `required_amount` Amount, required
          - `ui` string, required
          - `raw` string, required — A big integer represented as a string to preserve precision
          - `value_usd` number, nullable
        - `received_amount` Amount, required
          - `ui` string, required
          - `raw` string, required — A big integer represented as a string to preserve precision
          - `value_usd` number, nullable
        - `remaining_amount` Amount, required
          - `ui` string, required
          - `raw` string, required — A big integer represented as a string to preserve precision
          - `value_usd` number, nullable
        - `transactions` PaymentFundingTransaction[], required
          - `tx_hash` string, required
          - `amount` Amount, required
            - `ui` string, required
            - `raw` string, required — A big integer represented as a string to preserve precision
            - `value_usd` number, nullable
      - `recipient` string, required
      - `steps` PaymentStep[], required
        - `id` string
        - `purpose` string
        - `status` string
        - `expires_at` string, nullable
        - `rail` 'CRYPTO' | 'FIAT', required
        - `kind` 'deposit' | 'transaction' | 'stripe_onramp', required
        - `action` string
        - `description` string
        - `data` union
          - DepositStepData
            - `deposit_address` string, required
            - `currency` CurrencyBase, required
              - …
            - `amount` string, required — A big integer represented as a string to preserve precision
          - union
            - EVMPaymentData
              - …
            - BitcoinPaymentData
              - …
            - SolanaPaymentData
              - …
            - SuiPaymentData
              - …
          - StripeOnrampPaymentData
            - `session_id` string
            - `stripe_publishable_key` string, required
            - `status` string, required
            - `source_currency` 'usd' | 'eur' — Fiat source currency for Stripe embedded onramp intents
            - `destination_currency` 'usdc' | 'usdb' | 'usdsui' | 'usdt' | 'phantom_cash', required
            - `destination_network` 'arbitrum' | 'base' | 'bitcoin' | 'ethereum' | 'polygon' | 'solana' | 'sui' | 'tempo' | 'worldchain', required
            - `destination_amount` string, required
            - `wallet_address` string, required
      - `expires_at` string, date-time, required
      - `estimated_duration_seconds` number, nullable
      - `source_tx_hash` string, nullable
      - `destination_tx_hash` string, nullable
      - `fee_tx_hash` string, nullable
      - `refund` PaymentRefund
        - `address` string, nullable
        - `tx_hash` string, nullable
        - `reason` string, nullable
    - `metadata` OrderMetadata
      - `items` MetadataItems[]
        - `name` string, nullable
        - `description` string, nullable
        - `image` string, nullable
        - `quantity` integer, nullable
        - `unit_price` number, nullable
        - `currency` string, nullable
      - `refund` MetadataRefund
        - `name` string, nullable
        - `reason` string, nullable
        - `additional_info` string, nullable
        - `refund_amount` number, nullable
        - `currency` string, nullable
    - `settings` OrganizationSettings — Widget/client UI settings configured on the organization. Known fields are documented here; arbitrary extra JSON settings are also allowed.
      - `hide_footer` boolean
      - `card_payments` boolean
    - `hosted_url` string, required
  - `organization_id` string
  - `payment_url` string
  - `published_at` string, date-time, nullable
  - `updated_at` string, date-time

## Other responses

- `401` — Unauthorized
- `404` — Draft invoice not found
- `422` — Invalid request body or validation failed

---

[API](https://skmtc.net/coinvoyage/apis/coinvoyage-api-v3.md) · [All operations](https://skmtc.net/coinvoyage/apis/coinvoyage-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/coinvoyage/coinvoyage-api-v3/revisions/f3a3056f2c83/schema)