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

# Create an invoice

`POST /api/v1/invoices`

Creates as invoice

## Request body

- CreateInvoiceDto
  - `description` string
  - `customFields` InvoiceCustomFieldDto
    - `fields` InvoiceCustomFieldsDto[]
      - `name` string, required
      - `value` string, required
  - `dueDate` string, date-time
  - `footer` string
  - `fromInvoiceId` string, uuid
  - `metadata` object
  - `clientReferenceId` string
  - `visibility` string
  - `allowPromotionCodes` boolean — Enables user redeemable promotion codes.
  - `customerId` string, uuid
  - `lineItems` CreatePriceItemsDto
    - `data` CreateLineItemDto[], required — The line items to be used in checkout session
      - `priceId` string, uuid — The id of the price to use in checkout session
      - `priceData` PriceDataDto
        - `currency` 'usdc' | 'usdt' | 'pyusd' | 'eurc' | 'brett' | 'dai' | 'btc' | 'eth' | 'matic' | 'bnb' | 'sol' | 'busd' | 'trx' | 'food' | 'bonk' | 'wif' | 'goat' | 'spx' | 'truf' | 'pengu', required
        - `interval` 'day' | 'week' | 'month' | 'year'
        - `intervalCount` number — It is used to determine the frequency at which the subscription is billed. Only required for subscriptions
        - `unitAmount` integer, required — The unit amount in 8 decimals, represented as a whole integer
        - `productId` string, uuid — The id of the product for which this price is associated
        - `productData` ProductDataDto
          - `name` string, required — The name of the product. Displayed on the checkout page
          - `description` string — The description of the product. Displayed on the checkout page
          - `images` string[] — The url of product images. Displayed on the checkout page
          - `unitLabel` string — The label of the unit of the product. Displayed on the checkout page
          - `url` string — The url of the product
          - `metadata` object — The metadata of the product
          - `visibility` string
        - `type` 'one_time' | 'recurring' | 'streaming'
      - `quantity` number — The quantity of the line item
      - `periodStart` string, date-time
      - `periodEnd` string, date-time
      - `taxRateIds` string[]
  - `paymentSetting` CreateInvoicePaymentSettingDto
    - `allowedChains` PaymentSettingChainDto[] — The list of chains allowed for the payment. If not provided, all chains supported by the organization are enabled.
      - `chainId` number, required
      - `blacklistCurrencies` CryptoCurrency[] — The list of currencies to disable for the payment. Note: This field is only used for checkout session API atm.
      - `withdrawalAddress` string — This is optional, default withdrawal address configured in dashboard under settings > payment methods is used. The custom withdrawal address to use for this chain instead of stored default withdrawal address.
      - `withdrawalAddresses` CheckoutSessionSplitWithdrawalAddressDto[] — The list of withdrawal addresses to split the payment. If provided, the sum of all split percentages should be 100.
        - `splitPercentage` number, required
        - `address` string, required — The withdrawal address for the split percentage
    - `preferredChainId` number — The preferred chain's id
    - `preferredCurrency` 'usdc' | 'usdt' | 'pyusd' | 'eurc' | 'brett' | 'dai' | 'btc' | 'eth' | 'matic' | 'bnb' | 'sol' | 'busd' | 'trx' | 'food' | 'bonk' | 'wif' | 'goat' | 'spx' | 'truf' | 'pengu'
    - `allowSwap` boolean — Whether the user can swap the payment currency
  - `taxRateIds` string[]

## Response `200`

- InvoiceDto
  - `id` string, required
  - `createdAt` string, date-time
  - `updatedAt` string, date-time
  - `organizationId` string, uuid, required
  - `description` string
  - `total` integer
  - `subTotal` integer
  - `currency` 'usdc' | 'usdt' | 'pyusd' | 'eurc' | 'brett' | 'dai' | 'btc' | 'eth' | 'matic' | 'bnb' | 'sol' | 'busd' | 'trx' | 'food' | 'bonk' | 'wif' | 'goat' | 'spx' | 'truf' | 'pengu'
  - `customerId` string, uuid, required
  - `customer` CustomerDto, required
    - `name` string — The name
    - `email` string — The email
    - `phone` string — The phone
    - `organizationName` string — The organization name
    - `address` AddressDetailDto
      - `line1` string
      - `line2` string
      - `city` string
      - `state` string
      - `postalCode` string
      - `country` string
    - `id` string, uuid, required — Customer's id
    - `createdAt` string, date-time — Customer's created at
    - `updatedAt` string, date-time — Customer's updated at
    - `customerReferenceId` string — Customer's reference id
    - `shipping` FullAddressDetailDto
      - `name` string — The name
      - `email` string — The email
      - `phone` string — The phone
      - `organizationName` string — The organization name
      - `address` AddressDetailDto
        - `line1` string
        - `line2` string
        - `city` string
        - `state` string
        - `postalCode` string
        - `country` string
    - `taxIds` TaxIdsDto
      - `object` string
      - `data` TaxIdDto[]
        - `id` string, required
        - `createdAt` string, date-time
        - `updatedAt` string, date-time
        - `name` string
        - `value` string
        - `country` string
        - `customerId` string, uuid, required
    - `visibility` string
    - `metadata` object — Customer's metadata
    - `customerNumber` string, required — Customer number assigned by the system
  - `autoAdvance` boolean, required
  - `collectionMethod` 'charge_automatically' | 'send_invoice', required
  - `invoiceType` 'one_time' | 'recurring'
  - `customFields` InvoiceCustomFieldDto
    - `fields` InvoiceCustomFieldsDto[]
      - `name` string, required
      - `value` string, required
  - `paymentSettingId` string, uuid, required
  - `paymentSetting` PaymentSettingDto, required
    - `id` string, required
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `paymentMethodTypes` PaymentMethodType[] — A list of the types of payment methods
    - `allowedChains` PaymentSettingChainDto[] — The list of chains allowed for the payment. If not provided, all chains supported by the organization are enabled.
      - `chainId` number, required
      - `blacklistCurrencies` CryptoCurrency[] — The list of currencies to disable for the payment. Note: This field is only used for checkout session API atm.
      - `withdrawalAddress` string — This is optional, default withdrawal address configured in dashboard under settings > payment methods is used. The custom withdrawal address to use for this chain instead of stored default withdrawal address.
      - `withdrawalAddresses` CheckoutSessionSplitWithdrawalAddressDto[] — The list of withdrawal addresses to split the payment. If provided, the sum of all split percentages should be 100.
        - `splitPercentage` number, required
        - `address` string, required — The withdrawal address for the split percentage
    - `allowedCurrencies` CryptoCurrency[] — The list of currencies allowed for the payment.
    - `preferredChainId` number — The preferred chain's id
    - `preferredCurrency` 'usdc' | 'usdt' | 'pyusd' | 'eurc' | 'brett' | 'dai' | 'btc' | 'eth' | 'matic' | 'bnb' | 'sol' | 'busd' | 'trx' | 'food' | 'bonk' | 'wif' | 'goat' | 'spx' | 'truf' | 'pengu'
    - `allowSwap` boolean — Whether the user can swap the payment currency
    - `applyFee` boolean — Whether add a application fee to the user payment
    - `feePercentage` number, required — Percent that will be added to subtotal as a fee
    - `applyGasFee` boolean — Whether add a transaction fee to the user payment
    - `allowSplitPayments` boolean — Whether the user can split the payment
    - `slippagePercentage` number — The slippage percentage allowed for swaps and withdrawals
  - `status` 'draft' | 'open' | 'paid' | 'void' | 'uncollectible', required
  - `attempted` boolean, required
  - `attemptCount` number
  - `nextPaymentAttempt` string, date-time
  - `dueDate` string, date-time
  - `footer` string
  - `fromInvoiceId` string, uuid
  - `latestRevisionId` string, uuid
  - `invoicePdfUrl` string
  - `invoiceNumber` string
  - `paid` boolean, required
  - `paidOutOfBand` boolean
  - `metadata` object
  - `clientReferenceId` string
  - `lineItems` InvoicePriceItemsDto, required
    - `object` string
    - `data` InvoicePriceItemDto[]
      - `description` string
      - `periodStart` string, date-time
      - `periodEnd` string, date-time
      - `quantity` number
      - `price` PublicPriceDto, required
        - `id` string, required
        - `createdAt` string, date-time
        - `updatedAt` string, date-time
        - `billingScheme` 'per_unit'
        - `currency` 'usdc' | 'usdt' | 'pyusd' | 'eurc' | 'brett' | 'dai' | 'btc' | 'eth' | 'matic' | 'bnb' | 'sol' | 'busd' | 'trx' | 'food' | 'bonk' | 'wif' | 'goat' | 'spx' | 'truf' | 'pengu', required
        - `productId` string, uuid, required — Product's id
        - `interval` 'day' | 'week' | 'month' | 'year'
        - `intervalCount` number — It is used to determine the frequency at which the subscription is billed. Only required for subscriptions
        - `isActive` boolean — Whether the price is currently active
        - `usageType` 'licensed'
        - `type` 'one_time' | 'recurring' | 'streaming', required
        - `unitAmount` integer — The unit amount in 8 decimals, represented as a whole integer. If not provided, the unit amount will be calculated from unit_amount_decimal.
        - `unitAmountDecimal` string
        - `customUnitMax` integer — The maximum amount that can be billed per unit for this price. Only if unit amount is not provided
        - `customUnitMin` integer — The minimum amount that can be billed per unit for this price. Only if unit amount is not provided
        - `customPreset` integer — The default amount to fill in the amount field for this price on checkout. Only if unit amount is not provided
        - `customUnitAmountSuggestions` string[] — Amount suggestions for this price. Only if unit amount is not provided
        - `product` PublicProductDto, required
          - `id` string, required
          - `createdAt` string, date-time
          - `updatedAt` string, date-time
          - `name` string, required — The name of the product. Displayed on the checkout page
          - `description` string — The description of the product. Displayed on the checkout page
          - `isActive` boolean — Whether the product is currently active
          - `images` string[] — The url of product images. Displayed on the checkout page
          - `publicImages` string[] — Product images with absolute public url
          - `unitLabel` string — The label of the unit of the product. Displayed on the checkout page
          - `url` string — The url of the product
          - `defaultPriceId` string, uuid — Product's default price id
          - `metadata` object — The metadata of the product
          - `visibility` string
        - `metadata` object — A set of key-value pairs that you can attach to an object. It can be useful for storing additional information about the object in a structured format.
        - `visibility` string
      - `taxRates` LineTaxRateDto[]
        - `id` string, required
        - `name` string, required — The name of the tax rate.
        - `description` string — The description of the tax rate.
        - `country` string — The country of the tax rate.
        - `percentage` number, required — Percent that will be added to subtotal as a tax.
        - `type` 'exclusive' | 'inclusive', required
        - `isDefault` boolean, required
      - `amountTotal` integer
      - `amountSubtotal` integer
      - `amountTax` integer
      - `currency` 'usdc' | 'usdt' | 'pyusd' | 'eurc' | 'brett' | 'dai' | 'btc' | 'eth' | 'matic' | 'bnb' | 'sol' | 'busd' | 'trx' | 'food' | 'bonk' | 'wif' | 'goat' | 'spx' | 'truf' | 'pengu' | 'usd' | 'inr'
  - `finalizedAt` string, date-time
  - `paidAt` string, date-time
  - `markedUncollectibleAt` string, date-time
  - `visibility` string
  - `paymentIntentId` string, uuid
  - `url` string, required — The URL to redirect the customer to pay invoice
  - `subscriptionId` string
  - `periodStart` string, date-time
  - `periodEnd` string, date-time
  - `billingReason` 'subscription_cycle' | 'subscription_create' | 'subscription_update' | 'subscription' | 'manual' | 'upcoming' | 'subscription_threshold', required
  - `allowPromotionCodes` boolean — Enables user redeemable promotion codes.
  - `finalizeScheduleAt` string, date-time — The date on which invoice will be finalize and send
  - `totalTax` integer
  - `paymentIntent` PaymentIntentDto
    - `id` string, required
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `organizationId` string, uuid, required
    - `amount` integer
    - `amountReceived` integer
    - `currency` 'usdc' | 'usdt' | 'pyusd' | 'eurc' | 'brett' | 'dai' | 'btc' | 'eth' | 'matic' | 'bnb' | 'sol' | 'busd' | 'trx' | 'food' | 'bonk' | 'wif' | 'goat' | 'spx' | 'truf' | 'pengu' | 'usd' | 'inr'
    - `status` 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'requires_capture' | 'canceled' | 'succeeded', required
    - `paymentMethodId` string, uuid, required
    - `description` string
    - `paymentMethod` PaymentMethodDto
      - `id` string, required
      - `createdAt` string, date-time
      - `updatedAt` string, date-time
      - `assetId` string, uuid, required
      - `asset` AssetDto, required
        - `id` string, required — Asset id
        - `name` string, required — Asset name
        - `chainId` number, required — Asset chain id
        - `address` string, required — Asset address on chain
        - `currency` 'usdc' | 'usdt' | 'pyusd' | 'eurc' | 'brett' | 'dai' | 'btc' | 'eth' | 'matic' | 'bnb' | 'sol' | 'busd' | 'trx' | 'food' | 'bonk' | 'wif' | 'goat' | 'spx' | 'truf' | 'pengu' | 'usd' | 'inr', required
        - `symbol` string, required — Asset symbol
        - `decimals` number, required — Asset decimals in which it is represented on chain
        - `coingeckoId` string — Asset coingecko id
        - `superToken` SuperTokenDto
          - `address` string, required — SuperToken's address
          - `decimals` number, required
          - `symbol` string, required — SuperToken's symbol
        - `isEIP5827Supported` boolean, required — Is EIP5827 supported
      - `type` 'superfluid' | 'wallet' | 'allowance_based_recurring' | 'stripe' | 'binance_pay', required
      - `accountAddress` string
      - `billingDetails` FullAddressDetailDto
        - `name` string — The name
        - `email` string — The email
        - `phone` string — The phone
        - `organizationName` string — The organization name
        - `address` AddressDetailDto
          - `line1` string
          - `line2` string
          - `city` string
          - `state` string
          - `postalCode` string
          - `country` string
      - `customerId` string, uuid
      - `options` object
    - `paymentMethodTypes` PaymentMethodType[]
    - `transferAccountAddress` string
    - `transactions` TransactionDto[], required
      - `type` 'incoming' | 'outgoing' | 'event' | 'transfer', required
      - `transactionRelayId` string — Transaction relay id
      - `transactionHash` string — Transaction hash
      - `nonce` number — Transaction nonce
      - `gasLimit` number — Transaction gas limit used in payment
      - `validUntil` string — Transaction valid until
      - `fromAddress` string, required — Transaction from address
      - `toAddress` string, required — Transaction to address
      - `currency` 'usdc' | 'usdt' | 'pyusd' | 'eurc' | 'brett' | 'dai' | 'btc' | 'eth' | 'matic' | 'bnb' | 'sol' | 'busd' | 'trx' | 'food' | 'bonk' | 'wif' | 'goat' | 'spx' | 'truf' | 'pengu' | 'usd' | 'inr', required
      - `createdAt` string, date-time — Transaction created at
      - `amount` integer — Transaction amount in 8 decimals
      - `amountRaw` string, required — Transaction amount raw received from alchemy
      - `assetId` string, required — Transaction asset id
      - `asset` CheckoutSessionAssetDto, required
        - `id` string, required
        - `name` string, required
        - `address` string, required
        - `chainId` number, required
        - `currency` 'usdc' | 'usdt' | 'pyusd' | 'eurc' | 'brett' | 'dai' | 'btc' | 'eth' | 'matic' | 'bnb' | 'sol' | 'busd' | 'trx' | 'food' | 'bonk' | 'wif' | 'goat' | 'spx' | 'truf' | 'pengu' | 'usd' | 'inr', required
        - `symbol` string, required
        - `decimals` number, required
        - `coingeckoId` string
        - `isPublic` boolean, required
        - `superToken` SuperTokenDto
          - `address` string, required — SuperToken's address
          - `decimals` number, required
          - `symbol` string, required — SuperToken's symbol
        - `chain` ChainSlimDto, required
          - `id` number, required — Chain id
          - `name` string, required — Chain name
          - `icon` string, required — Chain icon
          - `currency` 'usdc' | 'usdt' | 'pyusd' | 'eurc' | 'brett' | 'dai' | 'btc' | 'eth' | 'matic' | 'bnb' | 'sol' | 'busd' | 'trx' | 'food' | 'bonk' | 'wif' | 'goat' | 'spx' | 'truf' | 'pengu' | 'usd' | 'inr', required
          - `blockExplorerTransactionUrl` string, required — Chain block explorer transaction url
          - `blockExplorerName` string, required — Chain block explorer name
          - `type` 'evm' | 'solana' | 'tron' | 'stripe' | 'binance_pay', required
          - `isBeta` boolean, required — Is beta asset
      - `transactionUrl` string — Transaction url
    - `paymentReceipt` PaymentReceiptDto
      - `id` string, required
      - `createdAt` string, date-time
      - `updatedAt` string, date-time
      - `organizationId` string, uuid, required
      - `paymentIntentId` string, uuid, required
      - `name` string
      - `receiptNumber` string, required
      - `uri` string
    - `canceledAt` string, date-time
    - `cancellationReason` string
    - `stripe` StripeDataDto
      - `paymentIntentId` string
      - `receiptUrl` string
      - `cardLast4` string
      - `displayName` string
    - `isMarkRefunded` boolean, nullable
    - `markRefundedAt` string, date-time, nullable
    - `markRefundedComment` string, nullable
  - `paymentIntentAttempt` PaymentIntentAttemptDto[] — The payment intent associated with the session. Payment intent is created when the session is created.
    - `id` string, required
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `errorCode` 'account_closed' | 'account_information_mismatch' | 'account_invalid' | 'account_number_invalid' | 'amount_too_large' | 'amount_too_small' | 'api_key_expired' | 'authentication_required' | 'balance_insufficient' | 'account_bad_routing_numbers' | 'account_declined' | 'account_exists' | 'account_restricted' | 'account_unusable' | 'account_unverified' | 'billing_invalid_mandate' | 'capture_charge_authorization_expired' | 'capture_unauthorized_payment' | 'charge_already_captured' | 'charge_already_refunded' | 'charge_disputed' | 'charge_exceeds_source_limit' | 'charge_expired_for_capture' | 'charge_invalid_parameter' | 'charge_not_refundable' | 'clearing_code_unsupported' | 'country_code_invalid' | 'country_unsupported' | 'coupon_expired' | 'customer_max_payment_methods' | 'customer_max_subscriptions' | 'debit_not_authorized' | 'email_invalid' | 'expired_card' | 'idempotency_key_in_use' | 'incorrect_address' | 'incorrect_number' | 'insufficient_funds' | 'intent_invalid_state' | 'intent_verification_method_missing' | 'invalid_characters' | 'invalid_charge_amount' | 'invalid_source_usage' | 'invoice_no_customer_line_items' | 'invoice_no_payment_method_types' | 'invoice_no_subscription_line_items' | 'invoice_not_editable' | 'invoice_on_behalf_of_not_editable' | 'invoice_payment_intent_requires_action' | 'invoice_upcoming_none' | 'livemode_mismatch' | 'lock_timeout' | 'missing' | 'no_account' | 'parameter_invalid_empty' | 'parameter_invalid_integer' | 'parameter_invalid_string_blank' | 'parameter_invalid_string_empty' | 'parameter_missing' | 'parameter_unknown' | 'parameters_exclusive' | 'payment_intent_action_required' | 'payment_intent_authentication_failure' | 'payment_intent_incompatible_payment_method' | 'payment_intent_invalid_parameter' | 'payment_intent_mandate_invalid' | 'payment_intent_payment_attempt_expired' | 'payment_intent_payment_attempt_failed' | 'payment_intent_unexpected_state' | 'payment_method_billing_details_address_missing' | 'payment_method_configuration_failures' | 'payment_method_currency_mismatch' | 'payment_method_customer_decline' | 'payment_method_invalid_parameter' | 'payment_method_invalid_parameter_testmode' | 'payment_method_not_available' | 'payment_method_provider_decline' | 'payment_method_provider_timeout' | 'payment_method_unactivated' | 'payment_method_unexpected_state' | 'payment_method_unsupported_type' | 'payout_reconciliation_not_ready' | 'payouts_limit_exceeded' | 'payouts_not_allowed' | 'postal_code_invalid' | 'processing_error' | 'product_inactive' | 'progressive_onboarding_limit_exceeded' | 'rate_limit' | 'refer_to_customer' | 'refund_disputed_payment' | 'resource_already_exists' | 'resource_missing' | 'return_intent_already_processed' | 'routing_number_invalid' | 'secret_key_required' | 'setup_attempt_failed' | 'setup_intent_authentication_failure' | 'setup_intent_invalid_parameter' | 'setup_intent_mandate_invalid' | 'setup_intent_setup_attempt_expired' | 'setup_intent_unexpected_state' | 'shipping_calculation_failed' | 'sku_inactive' | 'status_transition_invalid' | 'tax_id_invalid' | 'taxes_calculation_failed' | 'testmode_charges_only' | 'tls_version_unsupported' | 'token_already_used' | 'token_in_use' | 'transfer_source_balance_parameters_mismatch' | 'transfers_not_allowed' | 'url_invalid'
    - `type` 'api_error' | 'card_error' | 'idempotency_error' | 'invalid_request_error' | 'chain_error' | 'unknown', required
    - `declineCode` string
    - `paymentIntentId` string, uuid
    - `paymentMethodType` 'superfluid' | 'wallet' | 'allowance_based_recurring' | 'stripe' | 'binance_pay'
    - `docUrl` string
    - `status` 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'requires_capture' | 'canceled' | 'succeeded', required
  - `taxRateIds` string[]

## Other responses

- `500`

---

[API](https://skmtc.net/copperx/apis/copperx-api-2.md) · [All operations](https://skmtc.net/copperx/apis/copperx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/copperx/copperx-api-2/versions/c0bfbc37fb98/schema)