Skip to main content
POST
/
api
/
v1
/
invoice
/
Invoice Create Api
curl --request POST \
  --url https://api.justpaid.io/api/v1/invoice/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customer_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "invoice_number": "INV-2024-001",
  "invoice_date": "2024-03-21",
  "due_date": "2024-04-21",
  "currency": "USD",
  "description": "Monthly services for March 2024",
  "service_start_date": "2024-03-01",
  "service_end_date": "2024-03-31",
  "notes": "<string>",
  "recipients": [
    "<string>"
  ],
  "custom_fields": [
    {}
  ],
  "invoice_status": "draft",
  "line_items": [
    {
      "name": "Product A",
      "description": "Detailed description of the product or service",
      "quantity": 2,
      "unit_price": 100,
      "flat_fee": 10,
      "discount_amount": 5,
      "discount_percent": 10,
      "tax_rate": 10,
      "tax_name": "Sales Tax",
      "service_start_date": "2024-03-01",
      "service_end_date": "2024-03-31",
      "display_order": 2
    }
  ]
}'
{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "invoice_status": "draft",
  "amount": 1000,
  "currency": "USD",
  "invoice_number": "INV-2024-001",
  "invoice_date": "2024-03-21",
  "due_date": "2024-04-21",
  "service_start_date": "2024-03-01",
  "service_end_date": "2024-03-31",
  "description": "Monthly services for March 2024",
  "created_at": "2024-03-21T10:00:00Z",
  "is_recurring": false,
  "from_external_source": false,
  "external_source": "stripe",
  "external_source_id": "inv_123456",
  "payment_link": "https://app.justpaid.ai/portal/inv/123",
  "line_items": [
    {
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "unit_price": 123,
      "quantity": 123,
      "amount": 123,
      "currency": "<string>",
      "description": "<string>",
      "flat_fee": 123,
      "tax_rate": 123,
      "tax_amount": 123,
      "tax_name": "<string>",
      "discount_amount": 123,
      "discount_percent": 123,
      "service_start_date": "2023-12-25",
      "service_end_date": "2023-12-25",
      "display_order": 123
    }
  ],
  "file_url": "https://api.justpaid.ai/invoices/123.pdf",
  "customer": {
    "external_id": "CUST-001",
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "contact_name": "<string>",
    "email": "<string>",
    "additional_emails": [
      "<any>"
    ],
    "billing_emails": [
      "<any>"
    ],
    "phone_number": "<string>",
    "currency": "<string>",
    "tax_id": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Input schema for creating an invoice.

​
customer_uuid
string
required

UUID of the customer (required, must exist)

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
line_items
LineItemCreateIn · object[]
required

Invoice line items (at least one required)

Minimum length: 1
​
invoice_number
string | null

Unique invoice number (auto-generated if not provided)

Maximum length: 100
Example:

"INV-2024-001"

​
invoice_date
string<date> | null

Invoice date (defaults to today)

Example:

"2024-03-21"

​
due_date
string<date> | null

Payment due date

Example:

"2024-04-21"

​
currency
string
default:USD

ISO 4217 currency code

Example:

"USD"

​
description
string | null

Invoice description

Example:

"Monthly services for March 2024"

​
service_start_date
string<date> | null

Service period start date

Example:

"2024-03-01"

​
service_end_date
string<date> | null

Service period end date

Example:

"2024-03-31"

​
notes
string | null

Internal notes for the invoice

​
recipients
string[] | null

Additional email recipients

​
custom_fields
Custom Fields · object[] | null

Custom fields as list of {field_name, field_value}

​
invoice_status
string
default:draft

Initial invoice status (draft, ready-to-send, or sent)

Example:

"draft"

Response

Invoice created successfully

Output schema for invoice information.

​
uuid
string<uuid>

The unique identifier for the invoice

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
invoice_status
string

The current status of the invoice

Example:

"draft"

​
amount
number

The total amount due for the invoice

Example:

1000

​
currency
string

The currency code for the invoice

Example:

"USD"

​
invoice_number
string

The unique invoice number

Example:

"INV-2024-001"

​
invoice_date
string<date>

The date when the invoice was created

Example:

"2024-03-21"

​
due_date
string<date> | null

The date by which the invoice must be paid

Example:

"2024-04-21"

​
service_start_date
string<date> | null

The start date of the service period

Example:

"2024-03-01"

​
service_end_date
string<date> | null

The end date of the service period

Example:

"2024-03-31"

​
description
string | null

A description of the invoice

Example:

"Monthly services for March 2024"

​
created_at
string<date-time>

The timestamp when the invoice was created

Example:

"2024-03-21T10:00:00Z"

​
is_recurring
boolean

Indicates if this is a recurring invoice

Example:

false

​
from_external_source
boolean

Indicates if the invoice was created from an external source

Example:

false

​
external_source
string | null

The name of the external source if applicable

Example:

"stripe"

​
external_source_id
string | null

The ID of the invoice in the external system

Example:

"inv_123456"

​
payment_link
string | null

URL where the customer can pay this invoice

Example:

"https://app.justpaid.ai/portal/inv/123"

​
line_items
InvoiceLineItemOut2 · object[]

List of line items included in this invoice

​
file_url
string | null

URL to download the invoice PDF

Example:

"https://api.justpaid.ai/invoices/123.pdf"

​
customer
object | null

Details of the customer associated with this invoice Output schema for customer information.