User subscriptions

A UserSubscription assigns a club Subscription to one athlete for a defined period and, optionally, a limited number of activities. Its public identifier is UserClassSubscriptionId.

Choose an operation

Need	API reference
Synchronize all assignments	GET /UserSubscriptions
Synchronize currently active assignments	GET /UserSubscriptions/Active
List every assignment for one athlete	GET /Athletes/{userId}/UserSubscriptions
Read one assignment	GET /UserSubscriptions/{userSubscriptionId}
Create with explicit values	POST /UserSubscriptions
Create using plan values	POST /UserSubscriptions/Plans
Update validity or activity limits	PUT /UserSubscriptions/{userSubscriptionId}
Delete an assignment	DELETE /UserSubscriptions/{userSubscriptionId}

Suspension has its own workflow. See User subscription suspensions.

For one effective state computed from all assignments, use the individual or paginated membership summary. This view handles overlapping memberships, suspensions, future starts, disabling and ticket exhaustion. It also includes all assignments with product names, dates, tickets and suspension state, without per-product lookups.

List UserSubscriptions

Use the global operation for synchronization:

curl --request GET \
  --url "https://api-gw.uptivo.fit/club/UserSubscriptions?fromId=1&count=5000" \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>"

The default count is 1,000 and the maximum is 5,000. Repeat all parameters from the first request and continue with the opaque token:

GET /UserSubscriptions?fromId=1&count=5000&cursor=<NextCursor>

Store a separate checkpoint for each synchronization request. See Pagination and synchronization for checkpoint, retry, and reconciliation rules.

To retrieve all assignments for one athlete:

curl --request GET \
  --url https://api-gw.uptivo.fit/club/Athletes/300001/UserSubscriptions \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>"

The athlete-specific response is a plain JSON array and is not paginated. It returns current, future, expired, suspended, disabled, and exhausted assignments belonging to products of the selected club. It returns 404 Not Found if the athlete is absent or outside the selected club.

Use GET /UserSubscriptions/{userSubscriptionId} when processing an ID from a webhook or a stored relationship. A resource that is absent or belongs to another club returns 404 Not Found.

Meaning of active

GET /UserSubscriptions/Active applies all of these conditions at the time of the request:

• From is less than or equal to the current time;
• To is greater than or equal to the current time;
• Disabled is false;
• no suspension is active at the current instant;
• MaxActivities is 0, or AvailableActivities is greater than 0.

The time boundaries are inclusive. A scheduled suspension does not make the assignment inactive before its start; an automatic reactivation makes it active again from its reactivation instant. A future, expired, currently suspended, disabled, or exhausted limited assignment is not active. Use this operation when you need the server’s current eligibility view; do not reproduce it by checking dates alone.

An ID cursor discovers newly created UserSubscriptions, but it does not report an update or deletion of an older ID. Combine forward traversal with UserSubscription webhooks and periodic reconciliation.

Create with explicit values

Use direct creation when your integration supplies the validity interval and activity allowance:

curl --request POST \
  --url https://api-gw.uptivo.fit/club/UserSubscriptions \
  --header "Content-Type: application/json" \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>" \
  --data '{
    "ClassSubscriptionId": 500001,
    "UserId": 300001,
    "From": "2030-10-01T00:00:00+02:00",
    "To": "2030-10-31T23:59:59+01:00",
    "MaxActivities": 8
  }'

From and To must be between 2020-01-01 and 2100-01-01, and the interval must be at least one day. The athlete and product must belong to the selected club. On creation, AvailableActivities is initialized to MaxActivities.

Set MaxActivities to 0 for an unlimited assignment; its AvailableActivities is also 0, but the assignment is not exhausted.

The request can include a non-recurring ClassSubscriptionPlanId. The plan must belong to ClassSubscriptionId, but the endpoint still uses the explicit From, To, and MaxActivities values from the request. Use the plan-based operation below when those values must be derived from the plan.

An optional Transaction object can associate transaction information with the assignment. Use it only when Uptivo has confirmed the accounting workflow for the integration; consult the ClubTransactionOpDTO schema in the API reference for the complete contract.

Create from a plan

For a fixed-duration plan, let the server apply its duration and activity allowance:

curl --request POST \
  --url https://api-gw.uptivo.fit/club/UserSubscriptions/Plans \
  --header "Content-Type: application/json" \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>" \
  --data '{
    "ClassSubscriptionPlanId": 510001,
    "UserId": 300001,
    "From": "2030-10-01T00:00:00+02:00"
  }'

The plan selects the product, DurationDays, and MaxActivities. The server calculates To and initializes AvailableActivities. Persist the returned object rather than calculating the final end timestamp locally.

Both creation operations currently return 200 OK with the created object. They return 404 if the athlete or selected catalog resource is absent or outside the club scope, and 400 for an invalid interval, mismatched plan, or recurring plan.

Creating a UserSubscription for a product whose Type is not Trial also sets that club’s Athlete ClientStage to Client when it has a different value. This does not change the Athlete’s stage in other clubs. If it changes, Uptivo sends Athlete.Updated in addition to the UserSubscription event. Creating a Trial product does not make this stage change.

Update activity limits and validity

PUT /UserSubscriptions/{userSubscriptionId} is a complete state update, not a partial patch. Read the current object first and send all writable state:

curl --request PUT \
  --url https://api-gw.uptivo.fit/club/UserSubscriptions/600001 \
  --header "Content-Type: application/json" \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>" \
  --data '{
    "From": "2030-10-01T00:00:00+02:00",
    "To": "2030-10-31T23:59:59+01:00",
    "MaxActivities": 10,
    "AvailableActivities": 7
  }'

AvailableActivities is the remaining allowance and cannot exceed MaxActivities. For an unlimited assignment, keep both values at 0. Decrementing activities is normally performed by Uptivo when activities are consumed; write these counters only when the integration owns the corresponding business operation.

Externally managed recurring UserSubscriptions can be read through the Club API. Their From value cannot be changed and MaxActivities must remain 0. Do not treat the Club API update as a recurring-payment management endpoint.

The optional IsSuspended and ReactivationDate properties remain available for compatibility with existing clients. Omit both properties during an ordinary update to preserve any scheduled or active suspension. New integrations should use the dedicated suspension operations.

Delete a UserSubscription

Deletion removes the assignment rather than expiring it:

curl --request DELETE \
  --url https://api-gw.uptivo.fit/club/UserSubscriptions/600001 \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>"

The response contains the deleted UserSubscription snapshot. If the assignment has an active class booking, the API returns 409 Conflict with ErrorType: "SubscriptionInUse". Resolve the relevant bookings, then retrieve the UserSubscription again before deciding whether to retry.

Permissions, errors, and events

Reads require Read or ReadWrite access. Creating, updating, and deleting require ReadWrite. A missing or invalid credential returns 401; an inactive Club API license or insufficient key permission returns 403.

Successful writes produce UserSubscription webhook events. Treat an event as a signal and retrieve the current resource when possible. After a deletion, the event payload contains the final snapshot because a subsequent GET returns 404. See Errors and Receiving webhook events.