# Invoice Creation Guide

This guide explains how to create invoices using the Meow Billing API, from setting up products and customers to sending professional invoices with multiple payment options.

## Prerequisites

- A Meow account with billing capabilities enabled
- An API key with the following permissions:
  - `billing:products:read` and `billing:products:write` for product management
  - `billing:customers:read` and `billing:customers:write` for customer management
  - `billing:invoices:read` and `billing:invoices:write` for invoice creation
  - `billing:accounts:read` for viewing collection accounts


## Invoice Creation Workflow

Creating an invoice involves five main steps:

1. Create or retrieve a product to invoice for
2. Create or retrieve an invoicing customer
3. Check available payment method types for your entity
4. Select a collection account to receive payments
5. Create the invoice with line items and payment options


## Step 1: Create or Retrieve a Product

Products represent the goods or services you're invoicing for. You can either use existing products or create new ones.

### List Existing Products

First, check if you already have the product you need:


```bash
curl -X GET "https://api.meow.com/v1/billing/products" \
  -H "x-api-key: YOUR_API_KEY"
```

Example response:


```json
{
  "data": [
    {
      "id": "prod_123456789",
      "name": "Monthly Subscription",
      "description": "Premium monthly subscription service",
      "default_price": 99.99
    }
  ]
}
```

### Create a New Product

If you need to create a new product:


```bash
curl -X POST "https://api.meow.com/v1/billing/products" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Consulting Services",
    "description": "Professional consulting at hourly rate",
    "default_price": 150.00
  }'
```

Note the product `id` from the response - you'll need it when creating invoice line items.

## Step 2: Create or Retrieve an Invoicing Customer

Customers represent the entities you're invoicing. Each customer can have multiple invoices over time.

### List Existing Customers

Check your existing customers:


```bash
curl -X GET "https://api.meow.com/v1/billing/customers" \
  -H "x-api-key: YOUR_API_KEY"
```

### Create a New Customer

To create a new invoicing customer:


```bash
curl -X POST "https://api.meow.com/v1/billing/customers" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nickname": "Acme Corporation",
    "email": "billing@acme.com",
    "address": {
      "street_line_1": "123 Main Street",
      "street_line_2": "Suite 100",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    }
  }'
```

Save the customer `id` from the response for invoice creation.

## Step 3: Get Available Payment Method Types

Check which payment methods are available for your entity:


```bash
curl -X GET "https://api.meow.com/v1/billing/payment-method-types" \
  -H "x-api-key: YOUR_API_KEY"
```

Example response:


```json
{
  "payment_method_types": [
    "BANK_TRANSFER",
    "CARD",
    "ACH_DIRECT_DEBIT",
    "INTERNATIONAL_WIRE"
  ]
}
```

Note: The only type enabled by default is bank transfers. Card, ACH, and USDC payment types (USDC_ETHEREUM, USDC_SOLANA, USDC_BASE) have to be enabled for your business.

## Step 4: Select a Collection Account

Collection accounts are where invoice payments will be deposited. List your available accounts:


```bash
curl -X GET "https://api.meow.com/v1/billing/accounts" \
  -H "x-api-key: YOUR_API_KEY"
```

Example response:


```json
{
  "accounts": [
    {
      "id": "acct_987654321",
      "display_name": "Primary Operating Account",
      "account_number_mask": "••1234",
      "status": "open",
      "is_primary": true,
      "banking_product": "GRASSHOPPER"
    }
  ]
}
```

Choose the appropriate account `id` for receiving payments.

## Step 5: Create the Invoice

Now combine all the information to create your invoice:


```bash
curl -X POST "https://api.meow.com/v1/billing/invoices" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_123456789",
    "line_items": [
      {
        "product_id": "prod_987654321",
        "quantity": 10,
        "price": 150.00,
        "description": "10 hours of consulting services",
        "discount_percentage": 10,
        "discount_description": "10% early payment discount"
      }
    ],
    "invoice_date": "2025-06-20",
    "due_date": "2025-07-20",
    "payment_method_types": [
      "BANK_TRANSFER",
      "CARD",
      "ACH_DIRECT_DEBIT"
    ],
    "send_email_on_creation": true,
    "additional_recipient_emails": ["accounting@acme.com"],
    "note": "Thank you for your business!",
    "name": "INV-2025-001",
    "collection_account_id": "acct_987654321",
    "show_contact_address": true
  }'
```

### Key Invoice Fields

| Field | Description |
|  --- | --- |
| `customer_id` | The ID of the invoicing customer |
| `line_items` | Array of products/services being invoiced |
| `invoice_date` | When the invoice is issued (YYYY-MM-DD) |
| `due_date` | Payment due date (YYYY-MM-DD) |
| `payment_method_types` | Enabled payment methods (BANK_TRANSFER is always included) |
| `send_email_on_creation` | Whether to email the invoice immediately |
| `collection_account_id` | Account where payments will be deposited |


## Complete Example: Creating an Invoice from Scratch

Here's a complete example that creates a product, customer, and invoice:


```bash
# Step 1: Create a product
PRODUCT_ID=$(curl -X POST "https://api.meow.com/v1/billing/products" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website Development",
    "description": "Custom website development services",
    "default_price": 5000.00
  }' | jq -r '.id')

# Step 2: Create a customer
CUSTOMER_ID=$(curl -X POST "https://api.meow.com/v1/billing/customers" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nickname": "Tech Startup Inc",
    "email": "finance@techstartup.com"
  }' | jq -r '.id')

# Step 3: Get collection account (using first available)
ACCOUNT_ID=$(curl -X GET "https://api.meow.com/v1/billing/accounts" \
  -H "x-api-key: YOUR_API_KEY" | jq -r '.accounts[0].id')

# Step 4: Create the invoice
curl -X POST "https://api.meow.com/v1/billing/invoices" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"customer_id\": \"$CUSTOMER_ID\",
    \"line_items\": [
      {
        \"product_id\": \"$PRODUCT_ID\",
        \"quantity\": 1,
        \"description\": \"Website development - Phase 1\"
      }
    ],
    \"invoice_date\": \"$(date +%Y-%m-%d)\",
    \"due_date\": \"$(date -d '+30 days' +%Y-%m-%d)\",
    \"payment_method_types\": [\"BANK_TRANSFER\", \"CARD\"],
    \"send_email_on_creation\": true,
    \"collection_account_id\": \"$ACCOUNT_ID\"
  }"
```

## Understanding the Invoice Response

A successful invoice creation returns comprehensive details:


```json
{
  "id": "inv_123456789",
  "name": "INV-2025-001",
  "customer_id": "cust_123456789",
  "line_item_ids": ["line_987654321"],
  "invoice_date": "2025-06-20",
  "due_date": "2025-07-20",
  "payment_method_types": ["BANK_TRANSFER", "CARD", "ACH_DIRECT_DEBIT"],
  "send_email_on_creation": true,
  "additional_recipient_emails": ["accounting@acme.com"],
  "note": "Thank you for your business!",
  "collection_account_id": "acct_987654321",
  "created_at": "2025-06-20T10:30:00Z",
  "updated_at": null
}
```

## Best Practices for Invoice Creation

1. **Product Management**: Create reusable products for items you invoice frequently rather than using custom descriptions each time.
2. **Customer Data**: Keep customer information up-to-date, especially email addresses for invoice delivery.
3. **Payment Methods**: Only enable payment methods you're prepared to accept. Remember that customer consent is required for CARD and ACH_DIRECT_DEBIT.
4. **Testing**: Test your invoice flow in the sandbox environment before going live.
5. **Recurring Invoices**: Use the `recurring_schedule` field with RFC 2445 RRULE format for subscription-based billing. A tool like the following may be useful: [RRule Generator](https://icalendar.org/rrule-tool.html).
6. **Line Item Details**: Provide clear descriptions and use discount fields for transparency.


## Advanced Features

### Recurring Invoices

Create recurring invoices using RRULE format:


```json
{
  "recurring_schedule": "FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=1",
  // ... other invoice fields
}
```

### Custom Line Item Pricing

Override product defaults for specific invoices:


```json
{
  "line_items": [
    {
      "product_id": "prod_123",
      "quantity": 5,
      "price": 99.99,  // Override default price
      "description": "Special pricing for bulk order"
    }
  ]
}
```

## Support

If you need help or have questions:

- Email: support@meow.com
- Support Portal: https://support.meow.com
- API Status: https://status.meow.com