## PATCH /api/v2/account/service-consolidation

**Update monthly service invoice preferences**

Turns combined invoicing for monthly services on or off. It can also dismiss the suggestion to turn it on. Monthly services are VPS and web hosting on monthly billing. Send exactly one field: `enabled` (`true` or `false`) or `dismissSuggestion: true`. While the setting is on, each renewal invoice gathers every monthly service due within the following month onto one invoice. It has one line per service with its own period and is due on the earliest renewal. Invoices already issued are not merged or split. There is no payment-history, company or country requirement. The response is the setting read back after the change. A 503 means the change could not be confirmed. Read the setting with [`GET /api/v2/account/service-consolidation`](/endpoints/account/get-v2-account-service-consolidation/) before you retry.

### Related Endpoints

- `GET /api/v2/account/service-consolidation`: Get monthly service invoice preferences
- `GET /api/v2/account/invoice-lead`: Get invoice timing
- `PATCH /api/v2/account/invoice-lead`: Update invoice timing

### Headers

- `Authorization`: Bearer $HOSTUP_API_KEY
- Scope: `write:billing`
- `Content-Type`: application/json

### Request Body

- `enabled` (boolean, optional): `true` combines future renewal invoices for monthly services. `false` keeps one invoice per service.
- `dismissSuggestion` (boolean, optional): `true` stops the suggestion to turn the setting on.
  Allowed values: true

### Request Examples

#### Combine invoices

```bash
curl -X PATCH "https://cloud.hostup.se/api/v2/account/service-consolidation" \
  -H "Authorization: Bearer $HOSTUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'
```

```json
{
  "enabled": true
}
```

#### One invoice per service

```bash
curl -X PATCH "https://cloud.hostup.se/api/v2/account/service-consolidation" \
  -H "Authorization: Bearer $HOSTUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'
```

```json
{
  "enabled": false
}
```

#### Dismiss the suggestion

```bash
curl -X PATCH "https://cloud.hostup.se/api/v2/account/service-consolidation" \
  -H "Authorization: Bearer $HOSTUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dismissSuggestion": true
  }'
```

```json
{
  "dismissSuggestion": true
}
```

### Response Schema

- `enabled` (boolean, required): `true` when renewal invoices for monthly services are combined into one invoice a month.
- `available` (boolean, required): `false` while the setting is temporarily unavailable.
- `suggestion` (object, required): Whether to suggest turning the setting on.
- `suggestion.show` (boolean, required): `true` when the account has two or more upcoming service renewals on different dates and the setting is off, not turned off on purpose and not dismissed.
- `suggestion.settingsUrl` (string, required): Client-area path to the setting.
- `actions` (object, required)
- `actions.canToggle` (object, required): Whether the setting can be changed now.
- `actions.canToggle.allowed` (boolean, required): `true` when `PATCH /api/v2/account/service-consolidation` can change the setting now.
- `actions.canToggle.reason` (string, required, nullable): Why the setting cannot be changed. `null` when `allowed` is `true`.

### Responses

#### 200 - The setting read back after the change.
```json
{
  "enabled": true,
  "available": true,
  "suggestion": {
    "show": false,
    "settingsUrl": "/account?tab=billing#service-invoices"
  },
  "actions": {
    "canToggle": {
      "allowed": true,
      "reason": null
    }
  }
}
```

#### 400 - The body is not exactly one of `enabled` (boolean) or `dismissSuggestion: true`.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_request",
  "title": "Invoice preferences",
  "status": 400,
  "detail": "Send either enabled as a boolean or dismissSuggestion as true.",
  "code": "invalid_request",
  "instance": "/api/v2/account/service-consolidation"
}
```

#### 401 - Authentication is required.
```json
{
  "type": "https://developer.hostup.se/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required. Provide a valid API key or session.",
  "code": "unauthorized",
  "instance": "/api/v2/account/service-consolidation"
}
```

#### 403 - The API key lacks `write:billing`. A session that is not the account owner gets it too.
```json
{
  "type": "https://developer.hostup.se/errors/forbidden",
  "title": "Invoice preferences",
  "status": 403,
  "detail": "Account-owner access is required to change invoice preferences.",
  "code": "forbidden",
  "instance": "/api/v2/account/service-consolidation"
}
```

#### 404 - Not found. The resource does not exist or is not owned by the caller.
```json
{
  "type": "https://developer.hostup.se/errors/not_found",
  "title": "Not found",
  "status": 404,
  "detail": "The requested resource could not be found.",
  "code": "not_found",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 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": "Rate limit exceeded. Please try again later.",
  "code": "rate_limit_exceeded",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 500 - Internal error. Retry later or contact support if the issue persists.
```json
{
  "type": "https://developer.hostup.se/errors/internal_error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred. Retry later or contact support if the issue persists.",
  "code": "internal_error",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 503 - The change could not be confirmed. Read the setting again before you retry.
```json
{
  "type": "https://developer.hostup.se/errors/billing_state_unavailable",
  "title": "Invoice preferences",
  "status": 503,
  "detail": "The invoice preference could not be confirmed. Reload the setting before trying again.",
  "code": "billing_state_unavailable",
  "instance": "/api/v2/account/service-consolidation"
}
```
