## POST /api/v2/vps/{id}/mail-relay/quota-requests

**Create prepaid mail-relay quota invoice**

Create an unpaid invoice for a higher VPS mail relay monthly quota. The higher quota is applied only after the generated invoice is paid. Unused prepaid quota is credited to the account balance after the mail relay usage period closes. PAYG overage remains available only where the account has separately enabled it.

### Related Endpoints

- `GET /api/v2/vps/{id}/mail-relay`: Get VPS mail-relay status
- `POST /api/v2/vps/{id}/mail-relay/charge-consent`: Update VPS mail-relay billing consent
- `GET /api/v2/vps/{id}`: Get VPS details

### Headers

- `Accept`: application/json
- `Authorization`: Bearer YOUR_API_KEY
- Required API scope: `write:billing`
- `Content-Type`: application/json

### Parameters

- `id` (path, string, required): Public VPS ID from `GET /api/v2/vps` `data[].id`. Do not invent this value; use the exact ID returned by the referenced API response. Example: `vps_01hxa3b4c5d6e7f8g9h0j1k2m3`

### Request Body

- `requestedMonthlyLimit` (integer, required) [min: 16000]: Requested total monthly relay quota. Must be higher than the current effective monthly limit and must use 1,000-email increments. Example: `100000`
- `acknowledgePrepaidTerms` (boolean, required): Must be `true` to confirm that the caller understands the invoice must be paid before the higher quota is applied and unused prepaid quota is credited after the period. Example: `true`

### Request Examples

#### Create invoice for 100,000 emails/month

```bash
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-relay/quota-requests" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "requestedMonthlyLimit": 100000,
    "acknowledgePrepaidTerms": true
  }'
```

```json
{
  "requestedMonthlyLimit": 100000,
  "acknowledgePrepaidTerms": true
}
```

### Response Schema

- `id` (string, required): Prepaid quota purchase ID. Example: `d9dc8efa-c281-477d-86ef-758dd54a9a51`
- `status` (string, required) Example: `pending_payment`
  Allowed values: pending_payment
- `billingMode` (string, required) Example: `prepaid`
  Allowed values: prepaid
- `period` (string, required) Example: `2026-05`
- `periodStart` (string, required) Example: `2026-05-01`
- `periodEnd` (string, required) Example: `2026-05-31`
- `currentMonthlyLimit` (integer, required) Example: `15000`
- `requestedMonthlyLimit` (integer, required) Example: `100000`
- `purchasedExtraEmails` (integer, required) Example: `85000`
- `total` (number, required) Example: `42.5`
- `currencyCode` (string, required) Example: `EUR`
- `invoice` (object, required)
- `invoice.id` (string, required) Example: `inv_01hxa3b4c5d6e7f8g9h0j1k2m3`
- `invoice.number` (string, required) Example: `202600123`
- `invoice.status` (string, required) Example: `Unpaid`

### Responses

#### 201 - Prepaid quota invoice created. The higher quota is pending payment.
```json
{
  "id": "d9dc8efa-c281-477d-86ef-758dd54a9a51",
  "status": "pending_payment",
  "billingMode": "prepaid",
  "period": "2026-05",
  "periodStart": "2026-05-01",
  "periodEnd": "2026-05-31",
  "currentMonthlyLimit": 15000,
  "requestedMonthlyLimit": 100000,
  "purchasedExtraEmails": 85000,
  "total": 42.5,
  "currencyCode": "EUR",
  "invoice": {
    "id": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3",
    "number": "202600123",
    "status": "Unpaid"
  }
}
```

#### 400 - The request body is invalid or the requested limit is not higher than the current monthly limit.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_mail_relay_quota_request",
  "title": "Invalid mail relay quota request",
  "status": 400,
  "detail": "`requestedMonthlyLimit` must be in 1,000-email increments.",
  "code": "invalid_mail_relay_quota_request",
  "instance": "/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-relay/quota-requests",
  "errors": [
    {
      "pointer": "/requestedMonthlyLimit",
      "detail": "`requestedMonthlyLimit` must be in 1,000-email increments.",
      "code": "invalid_mail_relay_quota_request"
    }
  ]
}
```

#### 401 - Authentication is required.
```json
{
  "type": "https://developer.hostup.se/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required.",
  "code": "unauthorized",
  "instance": "/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-relay/quota-requests"
}
```

#### 403 - Forbidden. The caller lacks a required scope or does not own the resource.
```json
{
  "type": "https://developer.hostup.se/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The caller lacks a required scope or does not own the resource.",
  "code": "forbidden",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 404 - The requested VPS was not found or is not accessible.
```json
{
  "type": "https://developer.hostup.se/errors/vps_not_found",
  "title": "VPS not found",
  "status": 404,
  "detail": "The requested VPS could not be found.",
  "code": "vps_not_found",
  "instance": "/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-relay/quota-requests"
}
```

#### 409 - A prerequisite prevents invoice creation, such as an existing unpaid prepaid quota invoice, missing sender IP, or temporarily unavailable pricing.
```json
{
  "type": "https://developer.hostup.se/errors/mail_relay_quota_purchase_conflict",
  "title": "Mail relay quota purchase conflict",
  "status": 409,
  "detail": "There is already an unpaid prepaid mail relay quota invoice.",
  "code": "mail_relay_quota_purchase_conflict",
  "instance": "/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-relay/quota-requests",
  "invoice": {
    "id": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3",
    "status": "Unpaid"
  },
  "recovery": {
    "action": "pay_outstanding_invoice",
    "suggestedBody": null
  }
}
```

#### 429 - Rate limited. Retry after the limit resets. 429 responses include `Retry-After` seconds plus `X-RateLimit-*` headers.
```json
{
  "type": "https://developer.hostup.se/errors/rate_limit_exceeded",
  "title": "Too many requests",
  "status": 429,
  "detail": "Too many requests. Retry after the limit resets.",
  "code": "rate_limit_exceeded",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 500 - Unexpected error while creating the prepaid mail-relay quota invoice.
```json
{
  "type": "https://developer.hostup.se/errors/internal_error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred while creating the mail relay quota invoice.",
  "code": "internal_error",
  "instance": "/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-relay/quota-requests"
}
```