Appwrite Affiliates API

openapi: 3.0.0
info:
  title: Appwrite Affiliates API
  description: Appwrite backend as a service cuts up to 70% of the time and costs required for building a modern application. We abstract and simplify common development tasks behind a REST APIs, to help you develop your app in a fast and secure way. For full API documentation and tutorials go to [https://appwrite.io/docs](https://appwrite.io/docs)
  version: 2.0.0
  termsOfService: https://appwrite.io/policy/terms
  contact:
    name: Appwrite Team
    url: https://appwrite.io/support
    email: team@appwrite.io
  license:
    name: BSD-3-Clause
    url: https://raw.githubusercontent.com/appwrite/appwrite/master/LICENSE
servers:
- url: https://cloud.appwrite.io/v1
  description: Appwrite Cloud endpoint.
- url: https://{region}.cloud.appwrite.io/v1
  description: Appwrite Cloud regional endpoint. Replace `{region}` with your project region.
  variables:
    region:
      default: fra
      description: Appwrite Cloud region.
tags:
- name: affiliates
  description: The Affiliates service allows you to share referral codes, track conversions, and apply earned credits.
paths:
  /affiliates/links:
    get:
      summary: List affiliate links
      operationId: affiliatesListLinks
      tags:
      - affiliates
      description: 'List affiliate links for the current account.

        '
      responses:
        '200':
          description: Affiliate links list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/affiliateLinkList'
      deprecated: false
      x-appwrite:
        group: links
        demo: affiliates/list-links.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: account
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: queries
        description: 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/databases#querying-documents). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, status'
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
    post:
      summary: Create affiliate link
      operationId: affiliatesCreateLink
      tags:
      - affiliates
      description: 'Create a shareable affiliate link for the current account. Every console user is automatically in the affiliates program.

        '
      responses:
        '201':
          description: AffiliateLink
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/affiliateLink'
      deprecated: false
      x-appwrite:
        group: links
        demo: affiliates/create-link.md
        rate-limit: 10
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: account
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                linkId:
                  description: Link ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. This ID is the shareable referral code.
                  type: string
                  example: <LINK_ID>
                  x-appwrite:
                    idGenerator: ID.unique
                name:
                  description: 'Link name. Max length: 128 chars.'
                  type: string
                  default: ''
                  example: <NAME>
              required:
              - linkId
  /affiliates/links/{linkId}:
    get:
      summary: Get affiliate link
      operationId: affiliatesGetLink
      tags:
      - affiliates
      description: 'Get a single affiliate link owned by the current account.

        '
      responses:
        '200':
          description: AffiliateLink
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/affiliateLink'
      deprecated: false
      x-appwrite:
        group: links
        demo: affiliates/get-link.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: account
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: linkId
        description: Link ID.
        required: true
        schema:
          type: string
          x-appwrite:
            idGenerator: ID.unique
          example: <LINK_ID>
        in: path
    delete:
      summary: Delete affiliate link
      operationId: affiliatesDeleteLink
      tags:
      - affiliates
      description: 'Delete an affiliate link owned by the current account. Existing referrals and rewards keep their stored link IDs for history.

        '
      responses:
        '204':
          description: No content
      deprecated: false
      x-appwrite:
        group: links
        demo: affiliates/delete-link.md
        rate-limit: 10
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: account
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: linkId
        description: Link ID.
        required: true
        schema:
          type: string
          x-appwrite:
            idGenerator: ID.unique
          example: <LINK_ID>
        in: path
  /affiliates/referrals:
    get:
      summary: List affiliate referrals
      operationId: affiliatesListReferrals
      tags:
      - affiliates
      description: 'List referrals attributed to the current account''s affiliate links. Responses include privacy-safe metadata only (truncated user ID and signup country), never email or name. Referrals are created automatically on signup when the invite cookie is present.

        '
      responses:
        '200':
          description: Affiliate referrals list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/affiliateReferralList'
      deprecated: false
      x-appwrite:
        group: referrals
        demo: affiliates/list-referrals.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: account
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: queries
        description: 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/databases#querying-documents). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: linkId, referredUserMaskedId, referredUserCountry, status, attributedAt, expiresAt, convertedAt'
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
  /affiliates/rewards:
    get:
      summary: List affiliate rewards
      operationId: affiliatesListRewards
      tags:
      - affiliates
      description: 'List rewards earned by the current account from affiliate link conversions.

        '
      responses:
        '200':
          description: Affiliate rewards list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/affiliateRewardList'
      deprecated: false
      x-appwrite:
        group: rewards
        demo: affiliates/list-rewards.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: account
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: queries
        description: 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/databases#querying-documents). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: linkId, referralId, amount, status, teamId, creditId'
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
  /affiliates/rewards/{rewardId}:
    patch:
      summary: Update affiliate reward
      operationId: affiliatesUpdateReward
      tags:
      - affiliates
      description: 'Claim a pending affiliate reward by setting its status to `claimed`. Creates organization credits for the target organization. The current user must be an owner of that organization.

        '
      responses:
        '200':
          description: AffiliateReward
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/affiliateReward'
      deprecated: false
      x-appwrite:
        group: rewards
        demo: affiliates/update-reward.md
        rate-limit: 10
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: account
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: rewardId
        description: Reward ID
        required: true
        schema:
          type: string
          example: <REWARD_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  description: New reward status. Use `claimed` to claim the reward as organization credits.
                  type: string
                  example: claimed
                organizationId:
                  description: Organization ID to apply credits to when claiming.
                  type: string
                  example: <ORGANIZATION_ID>
              required:
              - status
              - organizationId
components:
  schemas:
    affiliateLink:
      description: AffiliateLink
      type: object
      properties:
        $id:
          type: string
          description: Link ID. This is the shareable referral code.
          example: my-campaign
        $createdAt:
          type: string
          description: Link creation date in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        $updatedAt:
          type: string
          description: Link update date in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        userId:
          type: string
          description: User ID of the link owner.
          example: 5e5ea5c16897e
        name:
          type: string
          description: Optional link name.
          example: Launch campaign
        status:
          type: string
          description: Link status. Can be one of `active` or `disabled`.
          example: active
      required:
      - $id
      - $createdAt
      - $updatedAt
      - userId
      - name
      - status
      example:
        $id: my-campaign
        $createdAt: '2020-10-15T06:38:00.000+00:00'
        $updatedAt: '2020-10-15T06:38:00.000+00:00'
        userId: 5e5ea5c16897e
        name: Launch campaign
        status: active
    affiliateLinkList:
      description: Affiliate links list
      type: object
      properties:
        total:
          type: integer
          description: Total number of links that matched your query.
          format: int32
          example: 5
        links:
          type: array
          description: List of links.
          items:
            $ref: '#/components/schemas/affiliateLink'
          example: []
      required:
      - total
      - links
      example:
        total: 5
        links: ''
    affiliateReferral:
      description: AffiliateReferral
      type: object
      properties:
        $id:
          type: string
          description: Referral ID.
          example: 5e5ea5c16897e
        $createdAt:
          type: string
          description: Referral creation date in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        $updatedAt:
          type: string
          description: Referral update date in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        linkId:
          type: string
          description: Affiliate link ID used for attribution.
          example: my-campaign
        referredUserMaskedId:
          type: string
          description: Privacy-safe truncated referred user ID.
          example: '****97e'
        referredUserCountry:
          type: string
          description: ISO 3166-1 alpha-2 country code of the referred user at signup, when available.
          example: us
        status:
          type: string
          description: Referral status. Can be one of `pending`, `converted`, or `expired`. `expired` is derived from `expiresAt` when still pending.
          example: pending
        attributedAt:
          type: string
          description: Attribution time in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        expiresAt:
          type: string
          description: Attribution expiry time in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        convertedAt:
          type: string
          description: Conversion time in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
          nullable: true
      required:
      - $id
      - $createdAt
      - $updatedAt
      - linkId
      - referredUserMaskedId
      - referredUserCountry
      - status
      - attributedAt
      - expiresAt
      example:
        $id: 5e5ea5c16897e
        $createdAt: '2020-10-15T06:38:00.000+00:00'
        $updatedAt: '2020-10-15T06:38:00.000+00:00'
        linkId: my-campaign
        referredUserMaskedId: '****97e'
        referredUserCountry: us
        status: pending
        attributedAt: '2020-10-15T06:38:00.000+00:00'
        expiresAt: '2020-10-15T06:38:00.000+00:00'
        convertedAt: '2020-10-15T06:38:00.000+00:00'
    affiliateReferralList:
      description: Affiliate referrals list
      type: object
      properties:
        total:
          type: integer
          description: Total number of referrals that matched your query.
          format: int32
          example: 5
        referrals:
          type: array
          description: List of referrals.
          items:
            $ref: '#/components/schemas/affiliateReferral'
          example: []
      required:
      - total
      - referrals
      example:
        total: 5
        referrals: ''
    affiliateReward:
      description: AffiliateReward
      type: object
      properties:
        $id:
          type: string
          description: Reward ID.
          example: 5e5ea5c16897e
        $createdAt:
          type: string
          description: Reward creation date in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        $updatedAt:
          type: string
          description: Reward update date in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        userId:
          type: string
          description: User ID of the reward owner.
          example: 5e5ea5c16897e
        linkId:
          type: string
          description: Affiliate link ID that earned this reward.
          example: my-campaign
        referralId:
          type: string
          description: Referral ID that earned this reward.
          example: 5e5ea5c16897e
        amount:
          type: number
          description: Reward amount in USD.
          format: double
          example: 10
        status:
          type: string
          description: Reward status. Can be one of `pending` or `claimed`.
          example: pending
        teamId:
          type: string
          description: Organization ID the reward was claimed on.
          example: 5e5ea5c16897e
          nullable: true
        creditId:
          type: string
          description: Credit document ID created when the reward was claimed.
          example: 5e5ea5c16897e
          nullable: true
      required:
      - $id
      - $createdAt
      - $updatedAt
      - userId
      - linkId
      - referralId
      - amount
      - status
      example:
        $id: 5e5ea5c16897e
        $createdAt: '2020-10-15T06:38:00.000+00:00'
        $updatedAt: '2020-10-15T06:38:00.000+00:00'
        userId: 5e5ea5c16897e
        linkId: my-campaign
        referralId: 5e5ea5c16897e
        amount: 10
        status: pending
        teamId: 5e5ea5c16897e
        creditId: 5e5ea5c16897e
    affiliateRewardList:
      description: Affiliate rewards list
      type: object
      properties:
        total:
          type: integer
          description: Total number of rewards that matched your query.
          format: int32
          example: 5
        rewards:
          type: array
          description: List of rewards.
          items:
            $ref: '#/components/schemas/affiliateReward'
          example: []
      required:
      - total
      - rewards
      example:
        total: 5
        rewards: ''
  securitySchemes:
    Project:
      type: apiKey
      name: X-Appwrite-Project
      description: Your project ID
      in: header
      x-appwrite:
        platforms:
        - client
        - server
        - console
        demo: <YOUR_PROJECT_ID>
externalDocs:
  description: Full API docs, specs and tutorials
  url: https://appwrite.io/docs