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

# Create an invoice

> Creates and issues an invoice, renders its PDF, fires invoice.issued, and emails the customer when a customerEmail is provided. Requires an invoice write permission.



## OpenAPI

````yaml /openapi.yaml post /invoices
openapi: 3.0.3
info:
  title: ArcenPay API
  description: >
    The ArcenPay REST API powers subscription billing, entitlements, usage
    metering,

    payment links, checkout sessions, and autonomous agent payments across EVM
    (BOT Chain,

    Base, Arc, Sepolia), Stellar, and Solana.


    Every endpoint that accepts an API key supports the `Authorization: Bearer
    <key>` header.

    Key prefixes: `sk_…` (secret), `rk_…` (restricted), `pk_…` (publishable,
    read-only),

    `sk_…`/`rk_…`. Company-scoped customer endpoints accept an embed access
    token

    (`arc_tok_…` or a signed JWT from `identify()`). See the Authentication page
    for the

    full endpoint auth matrix.


    Manage catalog, environments, invoices, webhooks, feature flags, and agent
    configuration

    from the *dashboard* — those are not part of the developer-facing API
    reference.
  version: 1.0.0
servers:
  - url: https://api.arcenpay.com/api/v1
    description: Production
  - url: http://localhost:3300/api/v1
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: Credentials
    description: >-
      API keys, secret/publishable/restricted credentials, and short-lived
      tokens.
  - name: Companies
    description: Customer organizations, identity synchronization, and feature overrides.
  - name: Users
    description: Customer end-users associated with company organizations.
  - name: Events
    description: Ingest customer usage events and identification signals.
  - name: Access control
    description: >-
      Real-time entitlement checks, feature flags, and metered credit
      consumption.
  - name: Subscriptions
    description: >-
      On-chain subscription activation, self-serve plan switching, proration,
      and cancellation.
  - name: Checkout sessions
    description: Hosted checkout session lifecycle and status lookup.
  - name: Payment links
    description: Crypto payment links and dynamic payment URLs.
  - name: Autonomous agents
    description: >-
      Agent permissions, budget checking, on-chain funding, and auto-topup
      dispatch.
  - name: Mandates
    description: Recurring billing authorizations and mandate lifecycle.
  - name: Coupons
    description: Discount code validation and proration quoting.
  - name: zkTLS proofs
    description: Zero-knowledge TLS proofs verification via Reclaim Protocol.
  - name: Public
    description: Unauthenticated payment link specifications and checkout sessions.
  - name: Escrow
    description: >-
      Autonomous commit-reveal escrow reservations, release settlement, and
      dispute handling.
  - name: Features
    description: Feature catalog definitions, feature types, and linked plan entitlements.
paths:
  /invoices:
    post:
      tags:
        - Invoices
      summary: Create an invoice
      description: >-
        Creates and issues an invoice, renders its PDF, fires invoice.issued,
        and emails the customer when a customerEmail is provided. Requires an
        invoice write permission.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceCreateRequest'
      responses:
        '201':
          description: The created invoice.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: '#/components/schemas/Invoice'
                  downloadUrl:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    InvoiceCreateRequest:
      type: object
      required:
        - lines
      properties:
        environmentMode:
          type: string
          enum:
            - DEVELOPMENT
            - PRODUCTION
          default: DEVELOPMENT
        customerEmail:
          type: string
          format: email
        customerName:
          type: string
        customerWallet:
          type: string
        currency:
          type: string
          default: USDC
        dueAt:
          type: string
          format: date-time
        planId:
          type: string
        metadata:
          type: object
          additionalProperties: true
        lines:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - description
              - unitAmount
            properties:
              description:
                type: string
              quantity:
                type: integer
                default: 1
              unitAmount:
                type: number
              taxRate:
                type: number
                default: 0
              metadata:
                type: object
                additionalProperties: true
    Invoice:
      type: object
      description: A Stripe-style invoice scoped to a team and workspace environment.
      properties:
        id:
          type: string
          example: in_abc123
        number:
          type: string
          example: INV-ACME-0001
        status:
          type: string
          enum:
            - DRAFT
            - ISSUED
            - PAID
            - VOID
            - OVERDUE
        currency:
          type: string
          example: USDC
        customerEmail:
          type: string
          nullable: true
        customerWallet:
          type: string
          nullable: true
        subtotal:
          type: string
          example: '100.000000'
        taxTotal:
          type: string
          example: '5.000000'
        total:
          type: string
          example: '105.000000'
        amountPaid:
          type: string
          example: '0.000000'
        amountCredited:
          type: string
          example: '0.000000'
        amountOutstanding:
          type: string
          example: '105.000000'
        dueAt:
          type: string
          format: date-time
          nullable: true
        issuedAt:
          type: string
          format: date-time
        planId:
          type: string
          nullable: true
        metadata:
          type: object
          additionalProperties: true
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceLineItem'
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - number
        - status
        - currency
        - total
    InvoiceLineItem:
      type: object
      properties:
        description:
          type: string
        quantity:
          type: integer
        unitAmount:
          type: string
          example: '100.000000'
        taxRate:
          type: string
          example: '5.0000'
        lineSubtotal:
          type: string
        lineTax:
          type: string
        lineTotal:
          type: string
  responses:
    BadRequest:
      description: Malformed request body or missing parameters.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              details:
                type: object
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              code:
                type: string
    Forbidden:
      description: Authenticated but not allowed (wrong key type or missing permission).
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              code:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sk_… / rk_… / pk_…

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.