Update Invoice

The Update Invoice endpoint allows you to modify existing invoices, including changing invoice details, updating line items, adjusting payment methods, and managing invoice status. This endpoint provides flexibility for invoice management while maintaining data integrity and audit trails.

Endpoint Details

Method: PATCH
URL: /api/v0/invoices/{invoice_id}
Content-Type: application/json
Authentication: Required (API Key & Secret)
Rate Limiting: 100 requests per minute
Idempotency: Supported (recommended for updates)

Authentication

This endpoint requires API key authentication using:

x-client-key: Your API client key
x-client-secret: Your API client secret

Path Parameters

Parameter	Type	Description	Required
invoice_id	string	Unique identifier for the invoice	Yes

Request Body

All fields are optional - only provide the fields you want to update.

Updatable Fields

Field	Type	Description	Validation
name	string	Invoice name/title	1-255 characters
email	string	Customer email address	Valid email format
address	string	Customer address	Optional string
phone_number	string	Customer phone number	Optional string
logo	string	Company logo URL	Valid URL format
items	array	Invoice line items	Array of item objects
due_date	string	Payment due date (YYYY-MM-DD)	Future date, ISO format
send_date	string	Invoice send date (YYYY-MM-DD)	ISO date format
status	enum	Invoice status	Valid InvoiceStatus enum
payment_methods	array	Accepted payment methods	Array of PaymentMethod enums
delivery	enum	Delivery method	EMAIL or MANUALLY
payment_link	boolean	Generate payment link	Boolean
partial_payment	boolean	Allow partial payments	Boolean
taxId	string	Tax configuration ID	Valid UUID, must exist

Item Structure

When updating items, provide the complete items array:

Field	Type	Description	Required
product_id	string	Product identifier	Yes
quantity	number	Quantity of the product	Yes

Item Updates: When updating items, provide the complete array of items you want on the invoice. Existing items will be replaced with the new array.

Request Schema

{
  "name": "string",
  "email": "string", 
  "address": "string",
  "phone_number": "string",
  "logo": "string",
  "items": [
    {
      "product_id": "string",
      "quantity": "number"
    }
  ],
  "due_date": "string",
  "send_date": "string", 
  "status": "enum",
  "payment_methods": ["enum"],
  "delivery": "enum",
  "payment_link": "boolean",
  "partial_payment": "boolean",
  "taxId": "string"
}

Response

Success Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "invoice_number": "INV-001234",
  "name": "Updated Website Development Services",
  "app_id": "app_123456789",
  "email": "updated@example.com",
  "address": "456 Updated St, New City, NC 54321",
  "phone_number": "+1-555-987-6543",
  "logo": "https://mycompany.com/assets/new-logo.png",
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "updated@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "company_name": "Example Corp"
  },
  "walletId": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
  "items": [
    {
      "id": "item_123456789",
      "product_id": "prod_123456789",
      "product": {
        "id": "prod_123456789",
        "name": "Website Development",
        "price": 5000.00,
        "currency": "USDC"
      },
      "quantity": 1,
      "line_total": 5000.00
    },
    {
      "id": "item_987654321",
      "product_id": "prod_987654321",
      "product": {
        "id": "prod_987654321",
        "name": "Additional Services",
        "price": 1000.00,
        "currency": "USDC"
      },
      "quantity": 2,
      "line_total": 2000.00
    }
  ],
  "due_date": "2024-03-01T00:00:00.000Z",
  "send_date": "2024-01-15T00:00:00.000Z",
  "date_created": "2024-01-15T10:30:00.000Z",
  "date_updated": "2024-01-25T14:45:00.000Z",
  "status": "OPEN",
  "payment_methods": ["CRYPTO", "BANK_TRANSFER", "CREDIT_CARD"],
  "delivery": "EMAIL",
  "payment_link": true,
  "partial_payment": true,
  "taxId": "tax_550e8400-e29b-41d4-a716-446655440123",
  "tax": {
    "id": "tax_550e8400-e29b-41d4-a716-446655440123",
    "name": "Sales Tax",
    "percentage": 8.25
  },
  "currency": "USDC",
  "subtotal": 7000.00,
  "tax_amount": 577.50,
  "total_amount": 7577.50,
  "amount_paid": 0.00,
  "amount_due": 7577.50,
  "is_overdue": false
}

Example Requests

curl -X PATCH "https://api.devdraft.ai/api/v0/invoices/550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "x-idempotency-key: $(uuidgen)" \
  -d '{
    "name": "Updated Website Development Services",
    "email": "updated@example.com",
    "due_date": "2024-03-01"
  }'

Error Responses

{
  "statusCode": 404,
  "message": "Invoice not found",
  "error": "Not Found",
  "details": "Invoice with ID '550e8400-e29b-41d4-a716-446655440000' does not exist"
}

Business Logic & Constraints

Status Transition Rules

DRAFT → OPEN

Allowed: Yes, when sending invoice to customer
Requirements: Must have valid customer email and items
Side Effects: Invoice becomes visible to customer, payment link activated

OPEN → PAID

Allowed: Automatically when full payment received
Requirements: Payment transactions totaling full amount
Side Effects: Invoice marked as completed, customer notified

PAID → OPEN

Allowed: Only if refund issued and balance remains
Requirements: Refund transaction reducing amount paid
Side Effects: Invoice reopened for remaining balance

Invalid Transitions

PAID → DRAFT: Cannot revert paid invoices to draft
PARTIALLYPAID → DRAFT: Cannot revert invoices with payments
PASTDUE → DRAFT: Cannot revert overdue invoices to draft

Update Restrictions

PAID Invoice Restrictions

Line Items: Cannot modify items on paid invoices
Amounts: Cannot change pricing on paid invoices
Payment Methods: Can add methods for future transactions
Customer Info: Can update contact information

Overdue Invoice Handling

Due Date: Can extend due date for overdue invoices
Payment Methods: Can add payment options to encourage payment
Status: Can manually mark as paid when payment confirmed
Reminders: Update triggers automatic reminder recalculation

Draft Invoice Flexibility

Full Edit: Draft invoices can be completely modified
Items: Add, remove, or update line items freely
Customer: Change customer details and billing information
Terms: Modify payment terms and due dates

Automatic Calculations

Recalculation: When line items or tax settings are updated, invoice totals are automatically recalculated including subtotal, tax amount, and total amount.

Financial Recalculation

Subtotal: Sum of all line item totals
Tax Amount: Applied based on taxId configuration
Total Amount: Subtotal + tax amount
Amount Due: Total amount - amount paid

Status Updates

Overdue Check: Due date changes trigger overdue status recalculation
Payment Status: Amount changes affect PAID/PARTIALLYPAID status
Days Until Due: Automatically calculated based on current date

Update Patterns

Status Management

const publishInvoice = async (invoiceId) => {
  // Validate invoice is ready to send
  const invoice = await getInvoice(invoiceId);
  
  if (invoice.status !== 'DRAFT') {
    throw new Error('Only draft invoices can be published');
  }
  
  if (!invoice.items || invoice.items.length === 0) {
    throw new Error('Invoice must have line items before publishing');
  }
  
  // Update status and send date
  return await updateInvoice(invoiceId, {
    status: 'OPEN',
    send_date: new Date().toISOString().split('T')[0]
  });
};

Use Cases

Invoice Correction

Fix errors in draft invoices before sending to customers

Payment Method Updates

Add or modify accepted payment methods based on customer preferences

Due Date Extensions

Extend payment deadlines for customers requesting more time

Line Item Adjustments

Modify invoice items based on scope changes or corrections

Status Management

Manage invoice lifecycle from draft through payment completion

Customer Information Updates

Update customer contact information and billing details

Implementation Examples

const InvoiceReviewWorkflow = {
  async reviewAndSend(invoiceId, reviewChanges) {
    // Apply review changes
    if (reviewChanges.lineItems) {
      await InvoiceUpdater.updateLineItems(invoiceId, reviewChanges.lineItems);
    }
    
    if (reviewChanges.dueDate) {
      await InvoiceUpdater.updateDueDate(invoiceId, reviewChanges.dueDate);
    }
    
    if (reviewChanges.paymentMethods) {
      await updateInvoice(invoiceId, { payment_methods: reviewChanges.paymentMethods });
    }
    
    // Send invoice
    return await InvoiceUpdater.sendInvoice(invoiceId);
  },

  async approveForPayment(invoiceId) {
    return await updateInvoice(invoiceId, {
      status: 'OPEN',
      payment_link: true
    });
  }
};

Best Practices

Validate Before Update

Always validate update data before sending to the API:

const validation = validateUpdate(updates);
if (!validation.isValid) {
  throw new Error(`Validation failed: ${validation.errors.join(', ')}`);
}

Use Idempotency Keys

Include idempotency keys for update operations to prevent duplicate changes:

const idempotencyKey = crypto.randomUUID();
// Include in headers for each update request

Check Current State

Retrieve current invoice state before making updates to avoid conflicts:

const currentInvoice = await getInvoice(invoiceId);
// Make decisions based on current state

Handle Status Restrictions

Respect status-based update restrictions:

if (invoice.status === 'PAID') {
  // Only allow limited updates
  delete updates.items;
  delete updates.due_date;
}

Audit Trail

Maintain audit trails for important updates:

const auditUpdate = async (invoiceId, updates, reason) => {
  const result = await updateInvoice(invoiceId, updates);
  
  // Log the update
  await logAuditEvent({
    type: 'invoice_updated',
    invoiceId,
    changes: updates,
    reason,
    timestamp: new Date().toISOString()
  });
  
  return result;
};

Security Considerations

Invoice updates affect financial data and should be carefully controlled with proper authorization and audit logging.

Authorization Checks

Only authenticated applications can update their own invoices
Status transition rules prevent unauthorized changes
Payment-related updates may require additional permissions

Data Validation

All update fields are validated for type and format
Business logic prevents invalid state transitions
Amount calculations are verified server-side

Audit Requirements

All invoice updates should be logged for audit purposes
Track who made changes, when, and what was changed
Maintain change history for compliance requirements

Rate Limiting

This endpoint is subject to the standard API rate limits:

Production: 100 requests per minute per API key
Development: 50 requests per minute per API key

POST /api/v0/invoices - Create a new invoice
GET /api/v0/invoices - List all invoices
GET /api/v0/invoices/{id} - Fetch specific invoice details
GET /api/v0/products - List products for line items

Home

Customers

Payment Links

Payment Intents

Products

Invoices

Taxes

Webhooks

Wallets

Transfers

Endpoint Details

Authentication

Path Parameters

Request Body

Updatable Fields

Item Structure

Request Schema

Response

Success Response (200 OK)

Example Requests

Error Responses

Business Logic & Constraints

Status Transition Rules

Update Restrictions

Automatic Calculations

Update Patterns

Status Management

Use Cases

Invoice Correction

Payment Method Updates

Due Date Extensions

Line Item Adjustments

Status Management

Customer Information Updates

Implementation Examples

Best Practices

Security Considerations

Rate Limiting

Home

Customers

Payment Links

Payment Intents

Products

Invoices

Taxes

Webhooks

Wallets

Transfers

​Endpoint Details

​Authentication

​Path Parameters

​Request Body

​Updatable Fields

​Item Structure

​Request Schema

​Response

​Success Response (200 OK)

​Example Requests

​Error Responses

​Business Logic & Constraints

​Status Transition Rules

​Update Restrictions

​Automatic Calculations

​Update Patterns

​Status Management

​Use Cases

Invoice Correction

Payment Method Updates

Due Date Extensions

Line Item Adjustments

Status Management

Customer Information Updates

​Implementation Examples

​Best Practices

​Security Considerations

​Rate Limiting

​Related Endpoints

Endpoint Details

Authentication

Path Parameters

Request Body

Updatable Fields

Item Structure

Request Schema

Response

Success Response (200 OK)

Example Requests

Error Responses

Business Logic & Constraints

Status Transition Rules

Update Restrictions

Automatic Calculations

Update Patterns

Status Management

Use Cases

Implementation Examples

Best Practices

Security Considerations

Rate Limiting

Related Endpoints