Sign in

v1

latestOpenAPI 3.1.0AGPL-3.0 license2026-07-1210336283.6 KB
Invoices

Create an invoice

Create an invoice for the authenticated team. The behavior depends on deliveryType: 'create' generates and finalizes the invoice immediately, 'create_and_send' also sends it to the customer, 'scheduled' schedules the invoice for automatic processing at the specified date.

post/invoices

Request body

fromDetailsobject

Sender details in TipTap JSONContent format

customerIdstring uuid required

Unique identifier for the customer (required)

paymentDetailsobject

Payment details in TipTap JSONContent format

noteDetailsobject

Additional notes for the invoice in TipTap JSONContent format

dueDatestring date-time

Due date of the invoice in ISO 8601 format. Defaults to issue date + payment terms (30 days) if not provided.

issueDatestring date-time

Issue date of the invoice in ISO 8601 format. Defaults to current date if not provided.

invoiceNumberstring

Invoice number as shown to the customer (auto-generated if not provided)

logoUrlstring nullable

URL of the logo to display on the invoice

vatnumber nullable

VAT amount for the invoice

taxnumber nullable

Tax amount for the invoice

discountnumber nullable

Discount applied to the invoice

topBlockobject

Custom content block to display at the top of the invoice in TipTap JSONContent format

bottomBlockobject

Custom content block to display at the bottom of the invoice in TipTap JSONContent format

amountnumber nullable

Total amount of the invoice

deliveryType'create' | 'create_and_send' | 'scheduled' required

How the invoice should be processed: 'create' - finalize immediately, 'create_and_send' - finalize and send to customer, 'scheduled' - schedule for automatic processing at specified date

scheduledAtstring date-time

Scheduled date of the invoice in ISO 8601 format with timezone offset (e.g., Z or +00:00). Required when deliveryType is 'scheduled'. Must be in the future.

Example request

{
  "template": {
    "title": "Invoice",
    "customerLabel": "Bill To",
    "fromLabel": "From",
    "invoiceNoLabel": "Invoice #",
    "issueDateLabel": "Issue Date",
    "dueDateLabel": "Due Date",
    "descriptionLabel": "Description",
    "priceLabel": "Rate",
    "quantityLabel": "Qty",
    "totalLabel": "Amount",
    "totalSummaryLabel": "Total",
    "vatLabel": "VAT",
    "taxLabel": "Sales Tax",
    "paymentLabel": "Payment Information",
    "noteLabel": "Notes",
    "logoUrl": "https://example.com/logo.png",
    "currency": "USD",
    "paymentDetails": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "Wire Transfer: Chase Bank, Account: 1234567890, Routing: 021000021"
            }
          ]
        }
      ]
    },
    "fromDetails": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "TechCorp Inc, 123 Business Ave, San Francisco, CA 94105"
            }
          ]
        }
      ]
    },
    "size": "letter",
    "includeVat": false,
    "includeTax": true,
    "discountLabel": "Discount",
    "includeDiscount": false,
    "includeUnits": true,
    "includeDecimals": true,
    "includePdf": true,
    "sendCopy": true,
    "includeQr": false,
    "dateFormat": "MM/dd/yyyy",
    "taxRate": 8.5,
    "vatRate": 0,
    "deliveryType": "create",
    "timezone": "America/Los_Angeles",
    "locale": "en-US"
  },
  "fromDetails": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "TechCorp Inc",
            "marks": [
              {
                "type": "strong"
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "123 Business Ave"
          }
        ]
      },
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "San Francisco, CA 94105"
          }
        ]
      }
    ]
  },
  "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "paymentDetails": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Wire Transfer:",
            "marks": [
              {
                "type": "strong"
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Chase Bank, Account: 1234567890"
          }
        ]
      },
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Routing: 021000021"
          }
        ]
      }
    ]
  },
  "noteDetails": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Payment is due within 30 days of invoice date."
          }
        ]
      },
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Thank you for your business!",
            "marks": [
              {
                "type": "italic"
              }
            ]
          }
        ]
      }
    ]
  },
  "dueDate": "2024-07-15T23:59:59.000Z",
  "issueDate": "2024-06-15T00:00:00.000Z",
  "invoiceNumber": "INV-2024-001",
  "logoUrl": "https://example.com/logo.png",
  "tax": 85,
  "topBlock": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Thank you for choosing TechCorp for your software development needs.",
            "marks": [
              {
                "type": "strong"
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "This invoice covers the development work completed in June 2024."
          }
        ]
      }
    ]
  },
  "bottomBlock": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Terms & Conditions:",
            "marks": [
              {
                "type": "strong"
              }
            ]
          }
        ]
      },
      {
        "type": "bulletList",
        "content": [
          {
            "type": "listItem",
            "content": [
              {
                "type": "paragraph",
                "content": [
                  {
                    "type": "text",
                    "text": "Payment is due within 30 days of invoice date"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "content": [
              {
                "type": "paragraph",
                "content": [
                  {
                    "type": "text",
                    "text": "Late payments may incur a 1.5% monthly service charge"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "content": [
              {
                "type": "paragraph",
                "content": [
                  {
                    "type": "text",
                    "text": "All work is subject to our standard terms of service"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Questions? Contact us at billing@techcorp.com or (555) 123-4567",
            "marks": [
              {
                "type": "italic"
              }
            ]
          }
        ]
      }
    ]
  },
  "amount": 1085,
  "lineItems": [
    {
      "name": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Web Development Services",
                "marks": [
                  {
                    "type": "strong"
                  }
                ]
              }
            ]
          },
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Custom React application with TypeScript",
                "marks": [
                  {
                    "type": "italic"
                  }
                ]
              }
            ]
          }
        ]
      },
      "quantity": 40,
      "price": 75,
      "tax": 8.5
    },
    {
      "name": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "UI/UX Design",
                "marks": [
                  {
                    "type": "strong"
                  }
                ]
              }
            ]
          },
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "User interface design and user experience optimization",
                "marks": [
                  {
                    "type": "italic"
                  }
                ]
              }
            ]
          }
        ]
      },
      "quantity": 20,
      "price": 50,
      "tax": 8.5
    }
  ],
  "deliveryType": "create",
  "scheduledAt": "2024-07-01T09:00:00.000Z"
}

Response

Invoice created successfully. Status depends on deliveryType: 'scheduled' for scheduled invoices, 'unpaid' for create/create_and_send.

idstring uuid required

Unique identifier for the draft invoice

status'draft' | 'overdue' | 'paid' | 'unpaid' | 'canceled' | 'scheduled' required

Current status of the invoice

createdAtstring required

Timestamp when the invoice was created (ISO 8601)

updatedAtstring required

Timestamp when the invoice was last updated (ISO 8601)

pdfUrlstring nullable required

Direct URL to download the invoice PDF

previewUrlstring nullable required

Direct URL to preview the invoice in browser

Example response

{
  "id": "b3b7e6e2-8c2a-4e2a-9b1a-2e4b5c6d7f8a",
  "status": "draft",
  "createdAt": "2024-06-01T07:00:00.000Z",
  "updatedAt": "2024-06-01T07:00:00.000Z",
  "pdfUrl": "https://app.midday.ai/api/download/invoice?token=eyJ...",
  "previewUrl": "https://app.midday.ai/i/eyJ..."
}