> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paycashless.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an invoice

> Create an invoice



## OpenAPI

````yaml POST /v1/invoices
openapi: 3.0.0
info:
  title: Paycashless API
  version: 1.1.0
servers:
  - url: https://api.paycashless.com
    description: Production
security: []
paths:
  /v1/invoices:
    post:
      tags:
        - invoices
      description: Create an invoice
      parameters:
        - schema:
            type: string
            minLength: 1
            description: SHA-512 HMAC signature of the request payload using the API secret
            example: >-
              5e73d044c44d733fcf819ad3409aaaddca840d421b69cb0b04e2c750fc62ece7526d36296237663ad1f06f62a730c0466516507196b3ce6567493cc52a7cf63d
          required: true
          description: SHA-512 HMAC signature of the request payload using the API secret
          name: Request-Signature
          in: header
        - schema:
            type: string
            pattern: ^\d{10}$
            description: UNIX timestamp when the request was created (in seconds)
            example: '1712336881'
          required: true
          description: UNIX timestamp when the request was created (in seconds)
          name: Request-Timestamp
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reference:
                  type: string
                acceptPartialPayments:
                  type: boolean
                  default: false
                description:
                  type: string
                currency:
                  type: string
                  enum:
                    - NGN
                    - USD
                sendEmail:
                  type: boolean
                  default: false
                autoFinalize:
                  type: boolean
                  default: false
                  description: >-
                    Whether to automatically finalize the invoice, invoice will
                    be in draft state if this is false
                  example: true
                callbackUrl:
                  type: string
                  format: uri
                  description: The URL to call when the invoice is paid
                  example: https://example.com/callback
                returnUrl:
                  type: string
                  format: uri
                  description: The URL to redirect to when the invoice is paid
                  example: https://example.com/return
                customer:
                  type: object
                  properties:
                    email:
                      type: string
                      format: email
                    name:
                      type: string
                    address:
                      type: string
                  required:
                    - email
                    - name
                    - address
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      quantity:
                        type: number
                      description:
                        type: string
                      price:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                        description: The price of the item in smallest currency unit
                        example: 100000
                    required:
                      - name
                      - quantity
                      - description
                      - price
                  maxItems: 20
                taxRateIds:
                  type: array
                  items:
                    type: string
                  description: The tax rates to apply to the invoice
                  example:
                    - txr_1
                maxInstallments:
                  type: number
                  default: 1
                  description: >-
                    The maximum number of installments the customer can pay in,
                    only required when acceptPartialPayments is true
                  example: 3
                daysUntilDue:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                  maximum: 1800
                  description: The number of days until the invoice is due
                  example: 30
                metadata:
                  type: object
                  additionalProperties:
                    nullable: true
                  description: Additional metadata for the invoice
                  example:
                    customer_id: '123'
                    order_id: '456'
              required:
                - reference
                - description
                - currency
                - customer
                - items
                - daysUntilDue
      responses:
        '201':
          description: Invoice created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                    enum:
                      - draft
                      - open
                      - paid
                      - partially_paid
                      - cancelled
                  customerId:
                    type: string
                  description:
                    type: string
                  currency:
                    type: string
                    enum:
                      - NGN
                      - USD
                  reference:
                    type: string
                  sendEmail:
                    type: boolean
                  dueDate:
                    type: string
                    format: date-time
                  liveMode:
                    type: boolean
                  number:
                    type: string
                    description: The number of the invoice
                    example: '0001'
                  amountDue:
                    type: integer
                    minimum: 0
                    exclusiveMinimum: true
                    description: >-
                      The total amount due for the invoice in smallest currency
                      unit
                    example: 100000
                  amountPaid:
                    type: integer
                    minimum: 0
                    exclusiveMinimum: true
                    description: >-
                      The total amount paid for the invoice in smallest currency
                      unit
                    example: 100000
                  totalInclusiveTaxAmount:
                    type: integer
                    minimum: 0
                    exclusiveMinimum: true
                    description: >-
                      The total inclusive tax amount for the invoice in smallest
                      currency unit
                    example: 10000
                  totalExclusiveTaxAmount:
                    type: integer
                    minimum: 0
                    exclusiveMinimum: true
                    description: >-
                      The total exclusive tax amount for the invoice in smallest
                      currency unit
                    example: 10000
                  taxRateIds:
                    type: array
                    items:
                      type: string
                    description: The tax rates applied to the invoice
                    example:
                      - tax_rate_1
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        quantity:
                          type: number
                        price:
                          type: integer
                          minimum: 0
                          exclusiveMinimum: true
                          description: The price of the item in smallest currency unit
                          example: 1000
                      required:
                        - id
                        - name
                        - quantity
                        - price
                  maxInstallments:
                    type: number
                    description: The maximum number of installments the customer can pay in
                    example: 3
                  hostedInvoiceUrl:
                    type: string
                    format: uri
                    description: The URL to the hosted invoice payment page
                    example: https://invoicing.paycashless.com/inv_123
                required:
                  - id
                  - status
                  - customerId
                  - description
                  - currency
                  - reference
                  - sendEmail
                  - dueDate
                  - liveMode
                  - number
                  - amountDue
                  - amountPaid
                  - totalInclusiveTaxAmount
                  - totalExclusiveTaxAmount
                  - taxRateIds
                  - items
                  - hostedInvoiceUrl

````