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

# One-Off Invoices

> Create, manage, and send one-off invoices for one-time charges

# One-Off Invoices

One-off invoices are standalone invoices for one-time charges that aren't tied to a recurring subscription. Use them for setup fees, professional services, custom work, or any other ad-hoc billing needs.

***

## Use Cases

| Use Case                  | Example                                  |
| ------------------------- | ---------------------------------------- |
| **Setup fees**            | Implementation, onboarding charges       |
| **Professional services** | Consulting, training, custom development |
| **Overages**              | Usage beyond subscription limits         |
| **Hardware/Equipment**    | Physical products or devices             |
| **Ad-hoc charges**        | One-time adjustments, corrections        |
| **Project work**          | Fixed-price project billing              |

***

## Create via Dashboard

<Steps>
  <Step title="From the Invoices section click on New Invoice">
    Start by navigating to the **Invoices** section and click on the **New Invoice** button.
  </Step>

  <Step title="Select or create a customer">
    On the new invoice page, select an existing customer or create a new one if needed.

    <Frame>
      <img src="https://mintcdn.com/alguna-20/SHr1INYd9aYWbwbe/images/invoicing/draft-invoice-a.png?fit=max&auto=format&n=SHr1INYd9aYWbwbe&q=85&s=78845e8da45b3b30099d64339944af12" width="1958" height="1552" data-path="images/invoicing/draft-invoice-a.png" />
    </Frame>
  </Step>

  <Step title="Select a due date and fill out the invoice memo">
    Choose the invoice due date and add any additional details or comments in the memo section.

    <Frame>
      <img src="https://mintcdn.com/alguna-20/SHr1INYd9aYWbwbe/images/invoicing/draft-invoice-b.png?fit=max&auto=format&n=SHr1INYd9aYWbwbe&q=85&s=59aecfea58e778e0214956223caf302f" width="1964" height="1556" data-path="images/invoicing/draft-invoice-b.png" />
    </Frame>
  </Step>

  <Step title="Add line items from your product catalog">
    Add the line items by selecting products from your catalog. Enter the quantity, and review the totals for accuracy.

    <Frame>
      <img src="https://mintcdn.com/alguna-20/SHr1INYd9aYWbwbe/images/invoicing/draft-invoice-c.png?fit=max&auto=format&n=SHr1INYd9aYWbwbe&q=85&s=5cbae633c4894608ec2657f4deb3e131" width="1962" height="1544" data-path="images/invoicing/draft-invoice-c.png" />
    </Frame>
  </Step>

  <Step title="Review the invoice before issuing">
    Review the entire invoice for correctness, including totals, taxes, and line items. Click the **Save Invoice** button to continue.

    <Frame>
      <img src="https://mintcdn.com/alguna-20/SHr1INYd9aYWbwbe/images/invoicing/draft-invoice-d.png?fit=max&auto=format&n=SHr1INYd9aYWbwbe&q=85&s=b30206506eb5a4ffd9771fd85bd23c3c" width="1372" height="1540" data-path="images/invoicing/draft-invoice-d.png" />
    </Frame>
  </Step>

  <Step title="Approve and send the invoice to customers">
    Once you have reviewed the invoice, click the **Issue Invoice** button to send the invoice to your customer.

    <Frame>
      <img src="https://mintcdn.com/alguna-20/SHr1INYd9aYWbwbe/images/invoicing/draft-invoice-e.png?fit=max&auto=format&n=SHr1INYd9aYWbwbe&q=85&s=f1ea6bb050afb544448e4fd8846d8725" width="1374" height="1552" data-path="images/invoicing/draft-invoice-e.png" />
    </Frame>
  </Step>
</Steps>

***

## Create via API

### Basic One-Off Invoice

```javascript theme={null}
const invoice = await alguna.invoices.create({
  accountId: 'acc_xyz789',
  type: 'one_off',
  dueDate: '2024-02-15',
  lineItems: [
    {
      description: 'Implementation Services',
      quantity: 1,
      unitPrice: '2500.00',
      currency: 'USD',
    },
  ],
});

// Issue the invoice to send to customer
await alguna.invoices.issue(invoice.id);
```

### With Product Catalog Items

```javascript theme={null}
const invoice = await alguna.invoices.create({
  accountId: 'acc_xyz789',
  type: 'one_off',
  dueDate: '2024-02-15',
  lineItems: [
    {
      productId: 'prod_setup_fee',
      quantity: 1,
    },
    {
      productId: 'prod_training',
      quantity: 8, // 8 hours of training
    },
  ],
});
```

### With Custom Line Items

```javascript theme={null}
const invoice = await alguna.invoices.create({
  accountId: 'acc_xyz789',
  type: 'one_off',
  dueDate: '2024-02-15',
  lineItems: [
    {
      description: 'Custom Integration Development',
      quantity: 1,
      unitPrice: '5000.00',
      currency: 'USD',
      taxCategory: 'services',
    },
    {
      description: 'API Documentation Review',
      quantity: 4,
      unitPrice: '150.00',
      currency: 'USD',
      taxCategory: 'services',
    },
  ],
  memo: 'Custom development work per SOW dated Jan 10, 2024',
});
```

### cURL Example

```bash theme={null}
curl -X POST https://api.alguna.io/invoices \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_xyz789",
    "type": "one_off",
    "due_date": "2024-02-15",
    "line_items": [
      {
        "description": "Professional Services",
        "quantity": 1,
        "unit_price": "1500.00",
        "currency": "USD"
      }
    ],
    "memo": "Consulting engagement - January 2024"
  }'
```

***

## Invoice Statuses

| Status           | Description                       |
| ---------------- | --------------------------------- |
| `draft`          | Invoice created but not finalized |
| `issued`         | Invoice sent to customer          |
| `paid`           | Payment received in full          |
| `partially_paid` | Partial payment received          |
| `past_due`       | Past due date, unpaid             |
| `void`           | Invoice canceled                  |
| `uncollectible`  | Marked as uncollectible           |

### Status Transitions

```mermaid theme={null}
graph LR
    A[draft] --> B[issued]
    B --> C[paid]
    B --> D[partially_paid]
    D --> C
    B --> E[past_due]
    E --> C
    E --> F[uncollectible]
    A --> G[void]
    B --> G
```

***

## Line Item Configuration

### Custom Line Item

```javascript theme={null}
{
  description: 'Custom Development Work',
  quantity: 1,
  unitPrice: '2500.00',
  currency: 'USD',
  taxCategory: 'services',
  metadata: {
    projectId: 'proj_123',
    hoursWorked: 25
  }
}
```

### From Product Catalog

```javascript theme={null}
{
  productId: 'prod_consulting',
  quantity: 10,
  // Price comes from product catalog
  // Can override with unitPrice if needed
}
```

### With Discount

```javascript theme={null}
{
  description: 'Annual Support Package',
  quantity: 1,
  unitPrice: '12000.00',
  discount: {
    type: 'percentage',
    value: 10, // 10% off
    reason: 'Multi-year commitment'
  }
}
```

### Tax-Exempt Line Item

```javascript theme={null}
{
  description: 'Tax-Exempt Service',
  quantity: 1,
  unitPrice: '500.00',
  taxBehavior: 'exempt',
  taxExemptReason: 'Resale for export'
}
```

***

## Invoice Options

### Payment Terms

```javascript theme={null}
const invoice = await alguna.invoices.create({
  accountId: 'acc_xyz789',
  type: 'one_off',
  paymentTerms: 'net_30', // net_7, net_15, net_30, net_45, net_60, net_90, net_120, due_on_receipt
  // or specific due date
  dueDate: '2024-03-01',
  lineItems: [...],
});
```

### Auto-Collection

Enable automatic payment collection:

```javascript theme={null}
const invoice = await alguna.invoices.create({
  accountId: 'acc_xyz789',
  type: 'one_off',
  autoCollect: true, // Charge saved payment method on issue
  lineItems: [...],
});
```

### Currency

```javascript theme={null}
const invoice = await alguna.invoices.create({
  accountId: 'acc_xyz789',
  type: 'one_off',
  currency: 'EUR', // Override customer's default currency
  lineItems: [
    {
      description: 'Service Fee',
      quantity: 1,
      unitPrice: '1000.00',
      currency: 'EUR',
    },
  ],
});
```

### Memo and Notes

```javascript theme={null}
const invoice = await alguna.invoices.create({
  accountId: 'acc_xyz789',
  type: 'one_off',
  memo: 'Public memo visible to customer',
  internalNotes: 'Internal note for your team only',
  footer: 'Thank you for your business!',
  lineItems: [...],
});
```

***

## Managing Draft Invoices

### Update Line Items

```javascript theme={null}
// Add line item
await alguna.invoices.addLineItem('inv_abc123', {
  description: 'Additional Hours',
  quantity: 5,
  unitPrice: '150.00',
});

// Update line item
await alguna.invoices.updateLineItem('inv_abc123', 'li_xyz789', {
  quantity: 10,
});

// Remove line item
await alguna.invoices.deleteLineItem('inv_abc123', 'li_xyz789');
```

### Update Invoice Details

```javascript theme={null}
await alguna.invoices.update('inv_abc123', {
  dueDate: '2024-03-01',
  memo: 'Updated payment terms',
});
```

### Delete Draft Invoice

```javascript theme={null}
await alguna.invoices.delete('inv_abc123');
// Only works for draft invoices
```

***

## Issue and Send

### Issue Invoice

```javascript theme={null}
const invoice = await alguna.invoices.issue('inv_abc123', {
  sendEmail: true,
  emailTo: ['billing@customer.com', 'finance@customer.com'],
});

console.log('Invoice number:', invoice.invoiceNumber);
console.log('Issued at:', invoice.issuedAt);
```

### Issue Without Email

```javascript theme={null}
const invoice = await alguna.invoices.issue('inv_abc123', {
  sendEmail: false,
});
```

### Resend Invoice

```javascript theme={null}
await alguna.invoices.resend('inv_abc123', {
  emailTo: ['billing@customer.com'],
  message: 'Please find your invoice attached.',
});
```

***

## Bulk Invoice Creation

Create multiple invoices at once:

```javascript theme={null}
const results = await alguna.invoices.createBulk([
  {
    accountId: 'acc_customer1',
    type: 'one_off',
    dueDate: '2024-02-15',
    lineItems: [
      { productId: 'prod_setup', quantity: 1 },
    ],
  },
  {
    accountId: 'acc_customer2',
    type: 'one_off',
    dueDate: '2024-02-15',
    lineItems: [
      { productId: 'prod_setup', quantity: 1 },
    ],
  },
]);

console.log('Created:', results.created.length);
console.log('Failed:', results.failed.length);
```

### Issue Multiple Invoices

```javascript theme={null}
await alguna.invoices.issueBulk({
  invoiceIds: ['inv_1', 'inv_2', 'inv_3'],
  sendEmail: true,
});
```

***

## Invoice Templates

### Create from Template

```javascript theme={null}
const invoice = await alguna.invoices.createFromTemplate({
  templateId: 'tmpl_services',
  accountId: 'acc_xyz789',
  variables: {
    projectName: 'Website Redesign',
    hours: 40,
  },
});
```

### Define Template

```javascript theme={null}
const template = await alguna.invoiceTemplates.create({
  name: 'Professional Services',
  lineItems: [
    {
      description: 'Consulting - {{projectName}}',
      unitPrice: '150.00',
      quantityVariable: 'hours',
    },
  ],
  paymentTerms: 'net_30',
  memo: 'Thank you for choosing our services.',
});
```

***

## Webhooks

| Event                    | Description             |
| ------------------------ | ----------------------- |
| `invoice.created`        | Invoice created         |
| `invoice.issued`         | Invoice issued and sent |
| `invoice.paid`           | Invoice fully paid      |
| `invoice.payment_failed` | Payment attempt failed  |
| `invoice.past_due`       | Invoice became past due |
| `invoice.voided`         | Invoice voided          |

### Example Handler

```javascript theme={null}
app.post('/webhooks/alguna', (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'invoice.created':
      console.log('New invoice:', event.data.id);
      break;

    case 'invoice.issued':
      const { id, invoiceNumber, total, accountId } = event.data;
      console.log(`Invoice ${invoiceNumber} issued for $${total}`);
      // Update your CRM, send Slack notification, etc.
      break;

    case 'invoice.paid':
      console.log('Invoice paid:', event.data.id);
      // Trigger fulfillment, grant access, etc.
      break;

    case 'invoice.past_due':
      console.log('Invoice past due:', event.data.id);
      // Trigger collection workflow
      break;
  }

  res.sendStatus(200);
});
```

***

## PDF Generation

### Get Invoice PDF

```javascript theme={null}
const pdf = await alguna.invoices.getPdf('inv_abc123');

// Returns URL to download PDF
console.log('PDF URL:', pdf.url);
console.log('Expires:', pdf.expiresAt);
```

### Bulk PDF Generation

```javascript theme={null}
const result = await alguna.invoices.generatePdfs({
  invoiceIds: ['inv_1', 'inv_2', 'inv_3'],
});

// Returns ZIP file with all PDFs
console.log('Download URL:', result.zipUrl);
```

### Custom PDF Settings

```javascript theme={null}
const pdf = await alguna.invoices.getPdf('inv_abc123', {
  language: 'de', // German
  includeTerms: true,
  logoPosition: 'right',
});
```

***

## Common Scenarios

### Setup Fee Invoice

```javascript theme={null}
const invoice = await alguna.invoices.create({
  accountId: 'acc_xyz789',
  type: 'one_off',
  dueDate: 'on_receipt',
  lineItems: [
    {
      productId: 'prod_setup_fee',
      quantity: 1,
    },
  ],
  autoCollect: true, // Charge immediately
});

await alguna.invoices.issue(invoice.id);
```

### Consulting Invoice

```javascript theme={null}
const invoice = await alguna.invoices.create({
  accountId: 'acc_xyz789',
  type: 'one_off',
  paymentTerms: 'net_30',
  lineItems: [
    {
      description: 'Strategy Consulting - January 2024',
      quantity: 20, // hours
      unitPrice: '200.00',
    },
    {
      description: 'Travel Expenses',
      quantity: 1,
      unitPrice: '450.00',
      taxBehavior: 'exempt',
    },
  ],
  memo: 'Payment due within 30 days. Late payments subject to 1.5% monthly interest.',
});
```

### Project Milestone Invoice

```javascript theme={null}
const invoice = await alguna.invoices.create({
  accountId: 'acc_xyz789',
  type: 'one_off',
  dueDate: '2024-02-15',
  lineItems: [
    {
      description: 'Project Alpha - Milestone 2: Design Complete',
      quantity: 1,
      unitPrice: '15000.00',
    },
  ],
  metadata: {
    projectId: 'proj_alpha',
    milestone: 2,
    totalMilestones: 5,
  },
});
```

***

## Voiding Invoices

### Void an Invoice

```javascript theme={null}
await alguna.invoices.void('inv_abc123', {
  reason: 'Customer requested cancellation',
});
```

### Void Restrictions

* Draft invoices can be deleted
* Issued/unpaid invoices can be voided
* Paid invoices cannot be voided (use credit notes instead)

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Descriptive Line Items" icon="list">
    Clear descriptions help customers understand what they're paying for.
  </Card>

  <Card title="Set Clear Due Dates" icon="calendar">
    Use consistent payment terms across your organization.
  </Card>

  <Card title="Enable Auto-Collection" icon="credit-card">
    For customers with saved payment methods, collect automatically.
  </Card>

  <Card title="Include Memos" icon="note-sticky">
    Add context about projects or agreements in the memo field.
  </Card>
</CardGroup>

***

## Troubleshooting

### Invoice Won't Issue

1. Check that all required fields are complete
2. Verify line items have valid prices
3. Ensure customer has a valid billing address

### Payment Not Processing

1. Verify customer has a valid payment method
2. Check auto-collect settings
3. Review payment gateway logs

### PDF Generation Fails

1. Check invoice has been issued
2. Verify branding settings are configured
3. Contact support if issue persists

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Recurring Invoices" icon="repeat" href="/invoices/recurring-invoices">
    Learn about subscription-based invoicing.
  </Card>

  <Card title="Credit Notes" icon="receipt" href="/invoices/credit-notes">
    Issue credits and refunds.
  </Card>
</CardGroup>