# Invoice Sending & Delivery

Send invoices via email or SMS, send reminders, and get the invoice PDF and QR code.

---

## Overview

Multiple ways to deliver invoices to customers:

- 📧 **Email** - Branded email with the invoice PDF attached
- 📱 **SMS** - Text message with the pay link
- 🔗 **Pay link** - Every invoice has its own pay URL (`shortLink`, or `{host}/pay/invoice/{linkId}`)
- 📄 **PDF download** - Direct PDF generation
- 📲 **QR code** - Scannable code for the pay link

All endpoints use the admin REST headers (`Authorization: Bearer YOUR_TOKEN` + `X-Tenant-ID`, or `x-api-key`).

Invoices are always delivered to the contact details **stored on the invoice** (`customerEmail`, `customerPhone`). To deliver to a different address, update the invoice first (Update Invoice for drafts, Edit Invoice otherwise). Message content comes from the platform templates and the merchant's branding — subject, body, CC/BCC and reply-to cannot be set per request.

---

## Send Invoice

Generic send: delivers by email or SMS.

### Endpoint

```http
POST /api/v1/invoices/:invoiceId/send
```

```bash
curl -X POST https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "email",
    "to": "customer@example.com"
  }'
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `method` | Yes | `email` or `sms` |
| `to` | Yes | Must be present, but delivery always goes to the invoice's stored email / phone |

**Response:**
```json
{
  "success": true,
  "data": { "message": "Invoice sent successfully" }
}
```

With `"method": "sms"` the message is `"Invoice sent via SMS successfully"`.

---

## Send via Email

Emails the invoice with its PDF attached. No request body.

### Endpoint

```http
POST /api/v1/invoices/:invoiceId/send-email
```

```bash
curl -X POST https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/send-email \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"
```

**Response:** `{ "success": true, "data": { "message": "Invoice sent successfully" } }`

---

## Send via SMS

Texts the pay link to the invoice's `customerPhone`. No request body.

### Endpoint

```http
POST /api/v1/invoices/:invoiceId/send-sms
```

```bash
curl -X POST https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/send-sms \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"
```

**Response:** `{ "success": true, "data": { "message": "Invoice sent via SMS successfully" } }`

### What sending does

- Sets the invoice status to `sent` and stamps `sentAt` — for any sendable status, including `viewed`, `partial` and `overdue`.
- The invoice is marked sent before the email/SMS is handed off; if the hand-off fails the call returns `500` but the status and `deliveryHistory` entry are already saved.
- Appends an entry to `deliveryHistory`: `{ "channel": "email" | "sms", "sentAt", "recipient", "actorId", "actorEmail" }`.
- Sending again (resend) uses the same endpoints.

### Errors

| Status | When |
|--------|------|
| `400` | No `customerEmail` (email) / `customerPhone` (SMS) on the invoice |
| `400` | Invoice is `paid`, `cancelled` or `expired` ("Cannot resend a paid, cancelled or expired invoice") |
| `400` | `/send` without `method` / `to`, or an unknown `method` |
| `404` | Invoice not found in your tenant |

---

## Send Reminder

Send a payment reminder email now, with the PDF attached. No request body.

### Endpoint

```http
POST /api/v1/invoices/:invoiceId/send-reminder
```

```bash
curl -X POST https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/send-reminder \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"
```

**Response:** `{ "success": true, "data": { "message": "Reminder sent successfully" } }`

Email only. Allowed for `sent`, `viewed`, `partial` and `overdue` invoices that have a `customerEmail`; otherwise `400`. Updates `reminderSentAt` and `reminderCount`.

---

## Get the Pay Link

There is no separate pay-link endpoint. The invoice returned by create / get carries it:

- `shortLink` — short URL, when the shortener minted one
- `linkId` — the full pay URL is `{host}/pay/invoice/{linkId}`

A full edit rotates `linkId`; the old link then returns `410 LINK_ROTATED`.

---

## Generate QR Code

### Endpoint

```http
GET /api/v1/invoices/:invoiceId/qr-code
```

```bash
curl https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/qr-code \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"
```

**Response:** a PNG data URL encoding the pay link. There are no size / format / colour options.

```json
{
  "success": true,
  "data": { "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..." }
}
```

---

## Download PDF

### Endpoint

```http
GET /api/v1/invoices/:invoiceId/pdf
```

```bash
curl https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/pdf \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -o invoice.pdf
```

Returns `application/pdf` as an attachment.

---

## Delivery Tracking

Delivery is tracked on the invoice itself (`GET /api/v1/invoices/:invoiceId`):

| Field | Description |
|-------|-------------|
| `sentAt` | Last time the invoice was sent |
| `deliveryHistory` | One entry per send, with channel and recipient |
| `viewedAt` / `viewCount` | When / how often the customer opened the pay link (status becomes `viewed`) |
| `reminderSentAt` / `reminderCount` | Manual reminders |

> **Note:** provider-level delivery status (delivered, opened, bounced) is not available via API.

---

## Webhooks

Delivery does not emit webhooks. The only invoice event is `invoice.paid` (see [Invoices](./invoices.md)).

---

## Best Practices

### ✅ DO:
- **Check contact details** before sending - delivery goes to the stored email/phone
- **Provide multiple options** - Email + SMS increases delivery
- **Make payment easy** - Share the pay link or QR code
- **Use reminders** for overdue invoices

### ❌ DON'T:
- **Don't spam** - Limit resends and reminders
- **Don't send drafts by accident** - a send moves the invoice to `sent`
- **Don't ignore bounces** - Update bad email addresses with Edit Invoice

---

## Troubleshooting

### Email Not Delivered

**Check:**
1. Is `customerEmail` set and correct on the invoice?
2. Not in the spam folder?
3. Email provider blocking?

### SMS Not Delivered

**Check:**
1. Is `customerPhone` set on the invoice?
2. Is it a valid US mobile number?

---

## Next Steps

- [Create invoices →](./invoices.md)
- [Invoice appearance →](./templates.md)
- [Payment tracking →](./payments.md)

---

**Need help?** Contact support@auxcore.net