Fetch Invoice

The Fetch Invoice endpoint allows you to retrieve comprehensive details about a specific invoice, including customer information, line items, payment transactions, and current status. This endpoint is essential for displaying invoice details, tracking payments, and managing invoice lifecycle.

Endpoint Details

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

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

Response

Success Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "invoice_number": "INV-001234",
  "name": "Website Development Services",
  "app_id": "app_123456789",
  "email": "client@example.com",
  "address": "123 Business St, Suite 100, Business City, BC 12345",
  "phone_number": "+1-555-123-4567",
  "logo": "https://mycompany.com/assets/logo.png",
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "client@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "company_name": "Example Corp",
    "phone": "+1-555-987-6543",
    "address": "456 Client Ave, Client City, CC 67890",
    "created_at": "2024-01-10T08:00:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  },
  "walletId": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
  "wallet": {
    "id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
    "currency": "USDC",
    "chain": "ethereum",
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "balance": 10000.00,
    "created_at": "2024-01-05T12:00:00.000Z"
  },
  "items": [
    {
      "id": "item_123456789",
      "product_id": "prod_123456789",
      "product": {
        "id": "prod_123456789",
        "name": "Website Development",
        "description": "Custom website development services including design, development, and deployment",
        "price": 5000.00,
        "currency": "USDC",
        "category": "Services",
        "created_at": "2024-01-01T00:00:00.000Z"
      },
      "quantity": 1,
      "unit_price": 5000.00,
      "line_total": 5000.00
    },
    {
      "id": "item_987654321",
      "product_id": "prod_987654321", 
      "product": {
        "id": "prod_987654321",
        "name": "SSL Certificate",
        "description": "1-year SSL certificate for secure website hosting",
        "price": 99.00,
        "currency": "USDC",
        "category": "Security",
        "created_at": "2024-01-01T00:00:00.000Z"
      },
      "quantity": 1,
      "unit_price": 99.00,
      "line_total": 99.00
    }
  ],
  "due_date": "2024-02-15T00:00:00.000Z",
  "send_date": "2024-01-15T00:00:00.000Z",
  "date_created": "2024-01-15T10:30:00.000Z",
  "date_updated": "2024-01-20T14:45:00.000Z",
  "status": "PARTIALLYPAID",
  "payment_methods": ["CRYPTO", "BANK_TRANSFER"],
  "delivery": "EMAIL",
  "payment_link": true,
  "payment_link_url": "https://pay.devdraft.ai/invoice/550e8400-e29b-41d4-a716-446655440000",
  "partial_payment": true,
  "taxId": "tax_550e8400-e29b-41d4-a716-446655440123",
  "tax": {
    "id": "tax_550e8400-e29b-41d4-a716-446655440123",
    "name": "Sales Tax",
    "description": "State sales tax for services",
    "percentage": 8.25,
    "active": true,
    "created_at": "2024-01-01T00:00:00.000Z"
  },
  "currency": "USDC",
  "subtotal": 5099.00,
  "tax_amount": 420.67,
  "total_amount": 5519.67,
  "amount_paid": 2759.84,
  "amount_due": 2759.83,
  "is_overdue": false,
  "days_until_due": 15,
  "transactions": [
    {
      "id": "tx_123456789",
      "amount": 2759.84,
      "currency": "USDC",
      "status": "COMPLETED",
      "payment_method": "CRYPTO",
      "transaction_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "created_at": "2024-01-20T14:30:00.000Z",
      "confirmed_at": "2024-01-20T14:35:00.000Z",
      "fee": 2.50,
      "net_amount": 2757.34
    }
  ],
  "payment_history": [
    {
      "date": "2024-01-20T14:30:00.000Z",
      "amount": 2759.84,
      "method": "CRYPTO",
      "status": "COMPLETED",
      "reference": "tx_123456789"
    }
  ],
  "reminders_sent": [
    {
      "type": "INITIAL",
      "sent_at": "2024-01-15T10:35:00.000Z",
      "method": "EMAIL"
    }
  ],
  "notes": [
    {
      "id": "note_123",
      "content": "Customer requested partial payment plan",
      "created_by": "user_456",
      "created_at": "2024-01-16T09:00:00.000Z"
    }
  ],
  "metadata": {
    "project_id": "proj_789",
    "contract_number": "CNT-2024-001",
    "milestone": "Phase 1 Completion"
  }
}

Response Fields

Core Invoice Fields

Field	Type	Description
id	string	Unique identifier for the invoice
invoice_number	string	Auto-generated invoice number (INV-XXXXXX)
name	string	Invoice name/title
app_id	string	Application ID that created the invoice
email	string	Customer email address
address	string	Customer address (optional)
phone_number	string	Customer phone number (optional)
logo	string	Company logo URL (optional)
customer_id	string	Customer identifier
walletId	string	Wallet used for payment processing
due_date	string	Payment due date (ISO 8601)
send_date	string	Date invoice was sent (ISO 8601)
date_created	string	Invoice creation date (ISO 8601)
date_updated	string	Last update date (ISO 8601)
status	enum	Current invoice status
payment_methods	array	Accepted payment methods
delivery	enum	Delivery method
payment_link	boolean	Whether payment link was generated
payment_link_url	string	URL for payment link (if enabled)
partial_payment	boolean	Whether partial payments are allowed

Financial Fields

Field	Type	Description
currency	enum	Invoice currency
subtotal	number	Subtotal before tax
tax_amount	number	Total tax amount
total_amount	number	Total amount including tax
amount_paid	number	Total amount paid
amount_due	number	Remaining amount due
is_overdue	boolean	Whether invoice is past due
days_until_due	number	Days until due date (negative if overdue)

Field	Type	Description
customer	object	Complete customer information
wallet	object	Payment wallet details
items	array	Invoice line items with products
tax	object	Tax configuration details
transactions	array	Payment transactions
payment_history	array	Simplified payment history
reminders_sent	array	Email reminders sent
notes	array	Internal notes and comments
metadata	object	Custom metadata fields

Example Requests

curl -X GET "https://api.devdraft.ai/api/v0/invoices/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Error Responses

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

Invoice Status Analysis

Status Meanings

DRAFT

Description: Invoice created but not yet sent to customer
Actions Available: Edit, send, delete
Payment Status: No payments expected
Customer Access: Customer cannot see draft invoices

OPEN

Description: Invoice sent and awaiting payment
Actions Available: Send reminders, update, receive payments
Payment Status: Full payment expected
Customer Access: Customer can view and pay invoice

PARTIALLYPAID

Description: Partial payment received, balance remaining
Actions Available: Send balance reminders, receive remaining payment
Payment Status: Partial payment received
Customer Access: Customer can pay remaining balance

PAID

Description: Invoice fully paid
Actions Available: View only, issue refunds
Payment Status: Payment complete
Customer Access: Customer can view paid invoice

PASTDUE

Description: Invoice overdue for payment
Actions Available: Send overdue notices, collection activities
Payment Status: Payment overdue
Customer Access: Customer can still pay overdue invoice

Payment Analysis

Payment Progress

Calculation: (amount_paid / total_amount) × 100
Thresholds: 0% (unpaid), 1-99% (partial), 100% (paid)
Status Impact: Affects invoice status and customer communications

Overdue Calculation

Logic: Current date > due_date
Days Overdue: Math.abs(days_until_due) when is_overdue = true
Risk Assessment: Increases collection risk with time

Payment Methods Tracking

Available Methods: Listed in payment_methods array
Used Methods: Tracked in transactions array
Analytics: Payment method preferences and success rates

Use Cases

Invoice Details Display

Show complete invoice information in customer portals and admin interfaces

Payment Tracking

Monitor payment progress and transaction history

Collections Management

Manage overdue invoices and collection activities

Customer Support

Access invoice details for customer service inquiries

Financial Reporting

Generate detailed reports and analytics

Audit Trail

Review invoice history for compliance and auditing

Implementation Examples

const InvoiceDisplay = ({ invoiceId }) => {
  const [invoice, setInvoice] = useState(null);
  const [analysis, setAnalysis] = useState(null);
  
  useEffect(() => {
    const loadInvoice = async () => {
      try {
        const invoiceData = await getInvoice(invoiceId);
        const analysisData = await getInvoiceWithAnalysis(invoiceId);
        
        setInvoice(invoiceData);
        setAnalysis(analysisData);
      } catch (error) {
        console.error('Failed to load invoice:', error);
      }
    };
    
    loadInvoice();
  }, [invoiceId]);
  
  if (!invoice) return <div>Loading...</div>;
  
  return (
    <div className="invoice-display">
      <div className="invoice-header">
        <h1>{invoice.invoice_number}</h1>
        <span className={`status-badge ${InvoiceUtils.getStatusColor(invoice.status)}`}>
          {invoice.status}
        </span>
      </div>
      
      <div className="payment-progress">
        <div className="progress-bar">
          <div 
            className="progress-fill" 
            style={{ width: `${analysis?.analysis?.paymentProgress || 0}%` }}
          />
        </div>
        <p>{InvoiceUtils.getStatusMessage(invoice)}</p>
      </div>
      
      <div className="invoice-details">
        <div className="customer-info">
          <h3>Bill To:</h3>
          <p>{invoice.customer.company_name}</p>
          <p>{invoice.customer.first_name} {invoice.customer.last_name}</p>
          <p>{invoice.address}</p>
        </div>
        
        <div className="line-items">
          <h3>Items:</h3>
          {invoice.items.map(item => (
            <div key={item.id} className="line-item">
              <span>{item.product.name}</span>
              <span>{item.quantity} × ${item.unit_price}</span>
              <span>${item.line_total}</span>
            </div>
          ))}
        </div>
        
        <div className="totals">
          <div>Subtotal: ${invoice.subtotal}</div>
          <div>Tax: ${invoice.tax_amount}</div>
          <div className="total">Total: ${invoice.total_amount}</div>
          <div className="paid">Paid: ${invoice.amount_paid}</div>
          <div className="due">Due: ${invoice.amount_due}</div>
        </div>
      </div>
    </div>
  );
};

Security Considerations

Invoice details contain sensitive financial and customer information. Ensure proper access controls and data protection.

Data Access Control

Invoice data is automatically scoped to your authenticated application
Only invoices created by your application are accessible
Customer payment information requires secure handling

Sensitive Information

Transaction hashes and payment details are sensitive
Customer personal and financial data requires protection
Implement proper audit logging for access tracking

Compliance Requirements

Maintain records for tax and regulatory compliance
Implement data retention and deletion policies
Ensure proper access controls for financial data

Performance Considerations

Data Loading

Invoice details include comprehensive related data
Consider caching frequently accessed invoices
Implement lazy loading for large transaction histories

Real-time Updates

Use webhooks to receive payment status updates
Implement optimistic UI updates for better experience
Cache invoice data with appropriate TTL values

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
PATCH /api/v0/invoices/{id} - Update invoice details
GET /api/v0/customers/{id} - Get customer details

Home

Customers

Payment Links

Payment Intents

Products

Invoices

Taxes

Webhooks

Wallets

Transfers

Endpoint Details

Authentication

Path Parameters

Response

Success Response (200 OK)

Response Fields

Core Invoice Fields

Financial Fields

Example Requests

Error Responses

Invoice Status Analysis

Status Meanings

Payment Analysis

Use Cases

Invoice Details Display

Payment Tracking

Collections Management

Customer Support

Financial Reporting

Audit Trail

Implementation Examples

Security Considerations

Performance Considerations

Rate Limiting

Home

Customers

Payment Links

Payment Intents

Products

Invoices

Taxes

Webhooks

Wallets

Transfers

​Endpoint Details

​Authentication

​Path Parameters

​Response

​Success Response (200 OK)

​Response Fields

​Core Invoice Fields

​Financial Fields

​Related Objects

​Example Requests

​Error Responses

​Invoice Status Analysis

​Status Meanings

​Payment Analysis

​Use Cases

Invoice Details Display

Payment Tracking

Collections Management

Customer Support

Financial Reporting

Audit Trail

​Implementation Examples

​Security Considerations

​Performance Considerations

​Rate Limiting

​Related Endpoints

Endpoint Details

Authentication

Path Parameters

Response

Success Response (200 OK)

Response Fields

Core Invoice Fields

Financial Fields

Related Objects

Example Requests

Error Responses

Invoice Status Analysis

Status Meanings

Payment Analysis

Use Cases

Implementation Examples

Security Considerations

Performance Considerations

Rate Limiting

Related Endpoints