# Invoice Recipients


## GET /api/v1/invoice-recipients/{recipientId}/auto-send-schedule

Get auto-send schedule

Fetch the auto-send schedule for a recipient. Returns null when no schedule is configured.

**Permissions:** 🔵 `invoices.read`

Path parameters:
- `recipientId` (string, required) — Recipient UUID

Response 200 — Default Response

```ts
{
  status: "success"
  data: {
    schedule?: {
      id?: string // uuid
      recipientId?: string // uuid
      isActive?: boolean
      scheduleType?: "weekly" | "monthly" | "interval_days"
      dayOfWeek?: number | null
      dayOfMonth?: number | null
      intervalDays?: number | null
      timeOfDay?: string
      timezone?: string
      nextRunAt?: string | null // date-time
      lastRunAt?: string | null // date-time
      lastRunStatus?: string | null
      createdAt?: string // date-time
      updatedAt?: string // date-time
    } | null
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## PUT /api/v1/invoice-recipients/{recipientId}/auto-send-schedule

Create or update auto-send schedule

Configure automatic sending of accumulated draft invoices for a recipient. Supported shapes: weekly (dayOfWeek + timeOfDay), monthly (dayOfMonth 1–28 + timeOfDay), or every N days (intervalDays + timeOfDay). The sweep runs every 15 minutes and sends all non-empty open drafts (one per reference); empty schedules are skipped silently.

**Permissions:** 🟠 `invoices.update`

Path parameters:
- `recipientId` (string, required) — Recipient UUID

Request body:

```ts
{
  isActive: boolean
  scheduleType: "weekly" | "monthly" | "interval_days"
  dayOfWeek?: number
  dayOfMonth?: number
  intervalDays?: number
  timeOfDay: string
  timezone?: string
}
```

Response 200 — Default Response

```ts
{
  status: "success"
  data: {
    id?: string // uuid
    recipientId?: string // uuid
    isActive?: boolean
    scheduleType?: "weekly" | "monthly" | "interval_days"
    dayOfWeek?: number | null
    dayOfMonth?: number | null
    intervalDays?: number | null
    timeOfDay?: string
    timezone?: string
    nextRunAt?: string | null // date-time
    lastRunAt?: string | null // date-time
    lastRunStatus?: string | null
    createdAt?: string // date-time
    updatedAt?: string // date-time
  } | null
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## DELETE /api/v1/invoice-recipients/{recipientId}/auto-send-schedule

Delete auto-send schedule

Remove the auto-send schedule for a recipient.

**Permissions:** 🔴 `invoices.delete`

Path parameters:
- `recipientId` (string, required) — Recipient UUID

Response 200 — Default Response

```ts
{
  status: "success"
  data: {
    deleted: boolean
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## GET /api/v1/invoice-recipients/{recipientId}/references

List recipient references

List references for an invoice recipient. Each reference accumulates its own draft invoice — a recipient can have multiple open invoices, one per reference.

**Permissions:** 🔵 `invoices.read`

Query parameters:
- `includeInactive` (boolean, optional) — Include deactivated references
- `locationId` (number, optional) — Viewing child location ID, used when reading references from an inherited recipient

Path parameters:
- `recipientId` (string, required) — Recipient UUID

Response 200 — Default Response

```ts
{
  status: "success"
  data: {
    references: Array<{
        id: string // uuid
        recipientId: string // uuid
        reference: string
        isActive: boolean
        createdAt: string // date-time
        updatedAt: string // date-time
      }>
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## POST /api/v1/invoice-recipients/{recipientId}/references

Create recipient reference

Add a reference to an invoice recipient. Upserts: re-adding an inactive reference reactivates it. References typed in the POS during invoice payment are created through this endpoint too.

**Permissions:** 🟢 `invoices.create`

Path parameters:
- `recipientId` (string, required) — Recipient UUID

Request body:

```ts
{
  reference: string
}
```

Response 201 — Default Response

```ts
{
  status: "success"
  data: {
    id: string // uuid
    recipientId: string // uuid
    reference: string
    isActive: boolean
    createdAt: string // date-time
    updatedAt: string // date-time
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## PUT /api/v1/invoice-recipients/{recipientId}/references/{referenceId}

Update recipient reference

Rename or activate/deactivate a recipient reference.

**Permissions:** 🟠 `invoices.update`

Path parameters:
- `recipientId` (string, required)
- `referenceId` (string, required)

Request body:

```ts
{
  reference?: string
  isActive?: boolean
}
```

Response 200 — Default Response

```ts
{
  status: "success"
  data: {
    id: string // uuid
    recipientId: string // uuid
    reference: string
    isActive: boolean
    createdAt: string // date-time
    updatedAt: string // date-time
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## GET /api/v1/invoice-recipients/guest-lookup

Look up guest by email

Resolve a guest user by exact email (case-insensitive) for connecting to an invoice recipient. Returns 404 when no user matches.

**Permissions:** 🔵 `invoices.read`

Query parameters:
- `locationId` (number, required)
- `email` (string, required)

Response 200 — Default Response

```ts
{
  status: "success"
  data: {
    userId: number
    uuid: string
    name?: string | null
    email: string
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```