Antavo Clubs API

openapi: 3.2.0
info:
  contact: {}
  title: Antavo Clubs API
  version: 1.0.0.0
servers:
- url: https://api.staging.antavo.com
  description: The Antavo staging environment
security:
- api_key: []
tags:
- name: Clubs
paths:
  /v1/clubs/{club_id}/history:
    get:
      tags:
      - Clubs
      summary: Retrieve club history
      description: This endpoint provides the history of actions performed in a club with optional filtering.
      parameters:
      - name: club_id
        in: path
        required: true
        description: The ID of the club to retrieve history for.
        schema:
          type: string
          example: 66cc313988befe60e3413e75
      - name: type
        in: query
        required: false
        description: Filter history by action type.
        schema:
          type: string
          enum:
          - club_applicant_accept
          - club_applicant_refuse
          - club_create
          - club_disband
          - club_point_donation
          - club_member_ban
          - club_member_unban
          - club_member_join
          - club_member_remove
          - club_ownership_assign
          - club_ownership_revoke
          - club_point_contribution
          - club_point_spent
          - club_point_add
          - club_point_remove
          example: club_create
      - name: customer_id
        in: query
        required: false
        description: Filter history by customer ID.
        schema:
          type: string
          example: 22cc313988befe60e3413e76
      - name: created_at
        in: query
        required: false
        description: Filter or order history by creation date.
        schema:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00+01:00'
      - name: offset
        in: query
        required: false
        description: Offsets the starting number of actions to return. This is used in pagination in conjunction with the limit query.
        schema:
          type: integer
          example: 0
      - name: limit
        in: query
        required: false
        description: Limits the number of actions returned in one response. Other values are accessible by pagination made accessible via the offset.
        schema:
          type: integer
          example: 20
      responses:
        '200':
          description: Response containing the history of actions taken on the specified club.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClubHistoryResponse'
        '400':
          description: A response indicating that the request was invalid. This response may contain different errors, such as limit, offset, or query parameter errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClubHistoryBadRequestErrorResponse'
        '404':
          description: A response indicating that the specified club could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClubHistoryNotFoundErrorResponse'
  /v1/clubs/{club_id}/members/{customer_id}:
    get:
      tags:
      - Clubs
      summary: Retrieve details of a specific club member
      description: This endpoint returns detailed information about a specific club member identified by their customer ID. The response includes the member's role, status, balance, and spending limits within the club.
      parameters:
      - name: club_id
        in: path
        required: true
        description: The unique identifier of the club to which the member belongs.
        schema:
          type: string
          example: 65d758e7f9cb852e19212e15
      - name: customer_id
        in: path
        required: true
        description: The unique identifier of the club member whose details are being requested.
        schema:
          type: string
          example: 62cc313988befe60e3413e75
      responses:
        '200':
          description: Successful response with details of the club member.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberDetailsResponse'
        '404':
          description: Not found response indicating the requested resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberNotFoundResponse'
  /v1/clubs/{club_id}/members:
    get:
      tags:
      - Clubs
      summary: List members of a specific club
      description: This endpoint returns the registered club members of a specified club. You can filter members by various parameters, such as member ID, role, and status. Pagination is also supported through offset and limit query parameters.
      parameters:
      - name: club_id
        in: path
        required: true
        description: The unique identifier of the club whose members are being requested.
        schema:
          type: string
          example: 65fc09f6cab4445deb626562
      - name: id.eq
        in: query
        required: false
        description: Filter to a specific club member by their unique identifier.
        schema:
          type: string
          example: 6604074cb8208607742492c7
      - name: role
        in: query
        required: false
        description: Filter by member type. Possible values are 'owner' or 'member'.
        schema:
          type: string
          enum:
          - owner
          - member
          example: member
      - name: status
        in: query
        required: false
        description: Filter by member status. Possible values are 'applicant', 'active', 'kicked', 'removed', or 'banned'.
        schema:
          type: string
          enum:
          - applicant
          - active
          - kicked
          - removed
          - banned
          example: active
      - name: offset
        in: query
        required: false
        description: Offsets the starting number of club members to return. This is used in pagination in conjunction with the limit query.
        schema:
          type: integer
          default: 0
          example: 0
      - name: limit
        in: query
        required: false
        description: Limits the number of members returned in one response. Other values are accessible by pagination made accessible via the offset.
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
          example: 20
      responses:
        '200':
          description: Successful response with the list of club members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClubMembersSuccessResponse'
        '400':
          description: Bad request due to invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClubMembersBadRequestResponse'
  /v1/clubs/{club_id}/point-expiry:
    get:
      tags:
      - Clubs
      summary: List expiring points by date
      description: This endpoint allows you to retrieve the list of expiring points within a given date range for a specific club.
      parameters:
      - name: club_id
        in: path
        required: true
        description: The ID of the club for which point expirations are being retrieved.
        schema:
          type: string
          example: 33cc313988befe60e3413e76
      - name: from
        in: query
        required: true
        description: The start date (inclusive) for retrieving expiring points. Must be in YYYY-MM-DD format.
        schema:
          type: string
          format: date
          example: '2024-03-14'
      - name: to
        in: query
        required: true
        description: The end date (inclusive) for retrieving expiring points. Must be in YYYY-MM-DD format. Maximum range is 30 days.
        schema:
          type: string
          format: date
          example: '2024-03-20'
      responses:
        '200':
          description: Response containing expiring points.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListExpirySuccessResponse'
              examples:
                success:
                  value:
                    status: success
                    metadata: []
                    payload:
                      expirations:
                      - status: expired
                        date: '2024-03-15'
                        amount: 100
                      - status: expiring
                        date: '2024-03-18'
                        amount: 200
                      total: 300
        '400':
          description: Bad request due to invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListExpiryErrorResponse'
              examples:
                invalid_date:
                  value:
                    status: error
                    error:
                      type: RuntimeException
                      code: 201121
                      message: Invalid date provided. Please provide a valid date in a supported format.
                date_range_exceeded:
                  value:
                    status: error
                    error:
                      type: RuntimeException
                      code: 201120
                      message: 'The date range exceeds the allowed limit of 30 days. Provided range: {} days.'
        '404':
          description: Club not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListExpiryErrorResponse'
              examples:
                club_not_found:
                  value:
                    status: error
                    error:
                      type: NotFoundException
                      code: 201054
                      message: Club not found
  /v1/clubs/{club_id}:
    get:
      tags:
      - Clubs
      summary: Retrieve club details
      description: This endpoint returns details of a specific club.
      parameters:
      - name: club_id
        in: path
        required: true
        description: The unique identifier of the club whose details are being requested. This ID must correspond to an existing club.
        schema:
          type: string
          example: 66056b8fc0380d23824277b7
      responses:
        '200':
          description: Successful response with club details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClubDetailsSuccessResponse'
        '404':
          description: Club not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClubDetailsNotFoundResponse'
  /v1/clubs/templates:
    get:
      tags:
      - Clubs
      summary: List club templates
      description: This endpoint returns the list of club templates based on various query parameters.
      parameters:
      - name: id.eq
        in: query
        description: Filter to a specific template by ID.
        required: false
        schema:
          type: string
        example: 123e4567-e89b-12d3-a456-426614174000
      - name: account_group_settings.accounts
        in: query
        description: Filter templates by accounts in Account Group Settings.
        required: false
        schema:
          type: string
        example: default_account
      - name: name
        in: query
        description: Filter templates by name.
        required: false
        schema:
          type: string
        example: Families and Friends
      - name: type
        in: query
        description: Filter templates by type.
        required: false
        schema:
          type: string
          enum:
          - public
          - private
        example: public
      - name: status
        in: query
        description: Filter templates by status.
        required: false
        schema:
          type: string
          enum:
          - active
          - draft
          - archived
        example: active
      - name: contribution_type
        in: query
        description: Filter templates by contribution type.
        required: false
        schema:
          type: string
          enum:
          - split_points
          - incentive_points
          - none
        example: split_points
      - name: expiration_type
        in: query
        description: Filter templates by expiration type.
        required: false
        schema:
          type: string
          enum:
          - rolling
          - calendar
          - no_expiration
        example: rolling
      - name: burn_eligibility
        in: query
        description: Filter templates by burn eligibility.
        required: false
        schema:
          type: string
          enum:
          - active_members
          - owner
        example: active_members
      - name: spending_limit
        in: query
        description: Filter templates by spending limit value.
        required: false
        schema:
          type: integer
        example: 500
      - name: account_group_settings.point_donation_enabled
        in: query
        description: Filter templates by whether point donation is enabled in account group settings.
        required: false
        schema:
          type: boolean
        example: true
      - name: limit_reset_type
        in: query
        description: Filter templates by donation limit reset type.
        required: false
        schema:
          type: string
          enum:
          - fix_date
          - first_spending
          - none
        example: fix_date
      - name: offset
        in: query
        description: Offsets the starting number of club templates to return. This is used in pagination in conjunction with the limit query.
        required: false
        schema:
          type: integer
          default: 0
          minimum: 0
        example: 10
      - name: limit
        in: query
        description: Limits the number of club templates returned in one response. Other values are accessible by pagination made accessible via the offset.
        required: false
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
        example: 50
      responses:
        '200':
          description: Request successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTemplatesSuccessResponse'
        '400':
          description: Bad request due to invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTemplatesBadRequestResponse'
              examples:
                limit_out_of_bounds:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201010
                      message: Limit must be between 1 and 100
                negative_offset:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201011
                      message: Offset cannot be negative
                invalid_query_parameters:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201014
                      message: Invalid query string parameter(s)
  /v1/clubs:
    get:
      tags:
      - Clubs
      summary: List clubs
      description: This endpoint returns the list of clubs based on various query parameters.
      parameters:
      - name: id.eq
        in: query
        required: false
        description: Filter to a specific club by ID.
        schema:
          type: string
        example: 987e6543-e89b-12d3-a456-426614174000
      - name: template_id
        in: query
        required: false
        description: Filter by associated template ID.
        schema:
          type: string
        example: 123e4567-e89b-12d3-a456-426614174000
      - name: name
        in: query
        required: false
        description: Filter by name.
        schema:
          type: string
        example: Family Moments Club
      - name: type
        in: query
        required: false
        description: Filter by template type.
        schema:
          type: string
          enum:
          - public
          - private
          example: public
      - name: status
        in: query
        required: false
        description: Filter by status.
        schema:
          type: string
          enum:
          - active
          - disbanded
          - fraudulent
          example: active
      - name: offset
        in: query
        required: false
        description: Offsets the starting number of clubs to return. This is used in pagination in conjunction with the limit query.
        schema:
          type: integer
          default: 0
        example: 10
      - name: limit
        in: query
        required: false
        description: Limits the number of clubs returned in one response. Other values are accessible by pagination made accessible via the offset.
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
        example: 50
      responses:
        '200':
          description: Request successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListClubsSuccessResponse'
        '400':
          description: Bad request due to invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListClubsBadRequestResponse'
              examples:
                limit_out_of_bounds:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201010
                      message: Limit must be between 1 and 100
                negative_offset:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201011
                      message: Offset cannot be negative
                invalid_query_parameters:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201012
                      message: Invalid query string parameter(s)
        '404':
          description: Request successful but no clubs found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListClubsEmptySuccessResponse'
    post:
      tags:
      - Clubs
      summary: Create a new club
      description: 'This endpoint allows users to create a new club, which can be assigned to different templates, allowing for varied functionalities and features based on specific user needs. To create a club, the user must provide key details, including the club''s name, associated template, and owner ID.


        Once created, the `club_create` event is automatically registered in both the club''s and the club owner''s event history.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: object
                  description: The name of the club, which can be provided in multiple languages. This parameter should be an object where each key corresponds to a language code, and the value is the club name in that language. At least one language must be provided.
                  properties:
                    en:
                      type: string
                      example: Family Moments Club
                template_id:
                  type: string
                  description: The unique identifier of the club template under which the new club is being created. This ID must reference an existing template in the system and should be active. If the specified template does not exist or is inactive, an error will be returned.
                  example: 123e4567-e89b-12d3-a456-426614174000
                owner_id:
                  type: string
                  description: The unique identifier of the customer who will own the new club. The customer associated with this ID must be active and should not already own another club or be a member of another club.
                  example: 62cc313988befe60e3413e75
      responses:
        '200':
          description: Club created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateClubSuccessResponse'
        '400':
          description: Bad request due to invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateClubBadRequestResponse'
              examples:
                property_empty:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201094
                      message: Property '%s' cannot be empty
                club_name_too_short:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201045
                      message: The club name is too short. It must be at least 3 characters long.
                club_template_not_exist:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201040
                      message: Club template with given ID does not exist
                club_template_not_active:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201041
                      message: Club template with given ID is not active
                only_active_customer_can_be_owner:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201044
                      message: Only active customer can be owner of a club
                customer_already_owns_club:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201042
                      message: The customer already owns a club
                customer_already_member:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201043
                      message: Customer is already a member of a club
  /v1/clubs/{club_id}/applicants/{customer_id}/accept:
    post:
      tags:
      - Clubs
      summary: Accept club membership
      description: 'This endpoint allows the club owner to accept an applicant''s request to join the club.


        When a customer is accepted, the `club_applicant_accept` event is automatically registered in both the club''s and the new member''s event history.

        '
      parameters:
      - name: club_id
        in: path
        required: true
        description: Unique identifier of the club to which the applicant is being accepted.
        schema:
          type: string
          example: 22cc313988befe60e3413e76
      - name: customer_id
        in: path
        required: true
        description: Unique identifier of the customer who is being accepted as a member of the club.
        schema:
          type: string
          example: 66cc313988befe60
      requestBody:
        required: true
        description: Information required to accept the applicant into the club.
        content:
          application/json:
            schema:
              type: object
              properties:
                actor:
                  type: string
                  description: ID of the customer who is making the action. Must be the owner of the club.
                  example: 33cc313988befe60e3413e76
                reason:
                  type: string
                  description: Reason for the acceptance (optional).
                  example: Reason
      responses:
        '200':
          description: Successful acceptance of club membership.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptSuccessResponse'
        '400':
          description: Bad request error responses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessBadRequestError'
              examples:
                actor_empty:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201094
                      message: Property 'actor' cannot be empty
                insufficient_permission:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201027
                      message: Actor has no permission to change status
                only_applicants_allowed:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201016
                      message: Only applicants can be accepted
                owners_cannot_be_applicants:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201017
                      message: Owners cannot be applicants
                member_limit_exceeded:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201078
                      message: Member limit exceeded
        '404':
          description: Not found error responses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessNotFoundError'
              examples:
                club_not_found:
                  value:
                    status: error
                    error:
                      type: NotFoundException
                      code: 201054
                      message: Club not found
                customer_member_applicant_not_found:
                  value:
                    status: error
                    error:
                      type: NotFoundException
                      code: 201079
                      message: The customer could not be found as a club member or applicant in this club
                customer_not_found:
                  value:
                    status: error
                    error:
                      type: NotFoundException
                      code: 320620
                      message: Customer not found
  /v1/clubs/{club_id}/applicants/{customer_id}/ban:
    post:
      tags:
      - Clubs
      summary: Ban an applicant from a club
      description: "This endpoint allows a user to ban an applicant from the club. The customer cannot apply to the club again in the future.\n\nWhen a customer is banned, the `club_applicant_ban` event is automatically registered in both the club's and the customer's event history.    \n"
      parameters:
      - name: club_id
        in: path
        required: true
        schema:
          type: string
          example: 65d758e7f9cb852e19212e15
          description: Unique identifier of the club from which the applicant is being banned.
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          example: 22cc313988befe60e3413e76
          description: Unique identifier of the club to which the applicant is being banned
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                actor:
                  type: string
                  description: ID of the customer who is making the action.
                  example: 33cc313988befe60e3413e76
                reason:
                  type: string
                  description: Reason for the ban (optional).
                  example: Returning exploiter.
      responses:
        '200':
          description: Response for banning a club applicant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessBanResponse'
        '400':
          description: Bad Request error responses for banning members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BanBadRequestError'
              examples:
                property_actor_empty:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201094
                      message: Property 'actor' cannot be empty
                actor_no_permission:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201027
                      message: Actor has no permission to change status
                owner_cannot_be_banned:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201024
                      message: Owners cannot be banned. Ownership must be reassigned!
                member_already_banned:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 201025
                      message: Banned club members cannot be banned again
        '404':
          description: Not Found error responses for banning members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BanNotFoundError'
              examples:
                club_not_found:
                  value:
                    status: error
                    error:
                      type: NotFoundException
                      code: 201054
                      message: Club not found
                customer_not_found:
                  value:
                    status: error
                    error:
                      type: NotFoundException
                      code: 320620
                      message: Customer not found
                club_member_or_applicant_not_found:
                  value:
                    status: error
                    error:
                      type: NotFoundException
                      code: 201079
                      message: The customer could not be found as a club member or applicant in this club
  /v1/clubs/{club_id}/applicants/{customer_id}/refuse:
    post:
      tags:
      - Clubs
      summary: Refuse a club applicant
      description: "This endpoint allows a user to refuse an applicant from the club. The customer can apply to the club again in the future.\n\nWhen a customer is refused, the `club_applicant_refuse` event is automatically registered in both the club's and the customer's event history.      \n"
      parameters:
      - name: club_id
        in: path
        required: true
        description: Unique identifier of the club from which the applicant is being refused.
        schema:
          type: string
          example: 65d758e7f9cb852e19212e15
      - name: customer_id
        in: path
      

# --- truncated at 32 KB (158 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/antavo/refs/heads/main/openapi/antavo-clubs-api-openapi.yml