> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Customer Activation
> Opt a customer in or out of the loyalty program, mirroring the dashboard include/exclude toggle.
Set a customer's loyalty program participation state (active/inactive). This mirrors the include/exclude toggle in the Gameball dashboard — use it on your storefront so customers can control participation, or manage participation from your backend.
The endpoint is **idempotent**:
* Opting out an already opted-out customer produces no side effects.
* Opting in an already opted-in customer produces no side effects.
* A state set via API is immediately reflected in the dashboard toggle, and vice versa.
* Gameball is the source of truth for participation status.
When a customer is opted out (`isActive: false`):
* No points are earned from events or purchases.
* No rewards or coupons are generated.
* No earnings, redemptions, or reward activity occurs.
* The customer is excluded from all campaign eligibility.
Prior activity (points, redemptions, achievements) is not undone — only future eligibility changes.
**Requires an existing customer.** Unknown customers return `404 Not Found`. This endpoint never creates a customer.
**Security:** Provide `apikey` header. `secretkey` is required on v4.1; on v4.0 required when High Security Mode is enabled.
### Idempotency
Calling the endpoint twice with the same customer and state always succeeds. On the first call that changes state, `stateChanged` is `true`. On a repeat call with the same state, `stateChanged` is `false` — no database writes, no side effects, no notifications.
### Errors
| Status | When |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `200` with `stateChanged: false` | Idempotent success — customer already in the target state |
| `400 Bad Request` | Missing or invalid payload (e.g. missing `isActive`), or a concurrent request for this customer is in progress |
| `401 Unauthorized` | Missing/invalid API key or secret key |
| `404 Not Found` | Customer does not exist, or customer ID is malformed |
### Notes and limitations
* There is no batch endpoint — manage multiple customers with sequential or parallel individual requests (respect [rate limits](/api-reference/overview/rate-limiting)).
* Changes take effect immediately for future earnings; assume a small propagation delay in edge cases.
* State changes are logged in your Gameball audit trail.
* This endpoint only sets participation. To modify other customer attributes, use [Create Customer](/api-reference/customers/management/create-customer) or the other customer management endpoints.
## OpenAPI
````yaml PUT /api/v4.0/integrations/customers/{customerId}/activate
openapi: 3.1.0
info:
title: Gameball API
description: >-
Gameball REST API v4.0 - Complete API reference for integrating loyalty,
gamification, and customer engagement features
version: 4.0.0
servers:
- url: https://api.gameball.co
security:
- bearerAuth: []
paths:
/api/v4.0/integrations/customers/{customerId}/activate:
put:
tags:
- Customers
summary: Update Customer Activation
description: >-
Set a customer's loyalty program participation state (active/inactive).
This mirrors the include/exclude toggle in the Gameball dashboard.
The endpoint is idempotent: opting out an already opted-out customer (or
opting in an already opted-in customer) produces no side effects.
`stateChanged` indicates whether the state actually changed.
When a customer is opted out (`isActive: false`): no points are earned
from events or purchases, no rewards or coupons are generated, and the
customer is excluded from all campaign eligibility. Prior activity is
not undone.
**Security:** Requires `apiKey` header. `secretKey` is required on v4.1;
on v4.0 required when High Security Mode is enabled.
**Requires an existing customer.** Unknown customers return `404 Not
Found`.
operationId: updateCustomerActivation
parameters:
- name: customerId
in: path
required: true
schema:
type: string
maxLength: 100
description: The customer's unique external identifier in your system.
example: cust-12345
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- isActive
properties:
isActive:
type: boolean
description: >-
Set to `true` to opt the customer in (Include); set to
`false` to opt the customer out (Exclude).
example: false
examples:
optOut:
summary: Opt customer out
value:
isActive: false
optIn:
summary: Opt customer in
value:
isActive: true
responses:
'200':
description: >-
Customer activation state updated (or already in the requested
state)
content:
application/json:
schema:
type: object
properties:
customerId:
type: string
description: Echo of the customer ID from the request.
example: cust-12345
isActive:
type: boolean
description: The customer's activation state after this request.
example: false
stateChanged:
type: boolean
description: >-
`true` if the state was different before this request and
changed as a result; `false` if the customer was already
in the target state (idempotent no-op).
example: true
examples:
changed:
summary: State changed
value:
customerId: cust-12345
isActive: false
stateChanged: true
idempotent:
summary: Already in target state
value:
customerId: cust-12345
isActive: false
stateChanged: false
'400':
description: >-
Missing or invalid request payload (e.g. missing `isActive`), or a
concurrent request for this customer is in progress.
'401':
description: >-
Missing, invalid, or expired API key; or invalid secret key (when
required).
'404':
description: >-
Customer does not exist in your Gameball account, or customer ID is
malformed.
security:
- apiKey: []
secretKey: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
apiKey:
type: apiKey
in: header
name: apikey
secretKey:
type: apiKey
in: header
name: secretkey
````