openapi: 3.0.3
info:
  title: Friendbuy Merchant API
  description: >-
    The Friendbuy Merchant API is the server-to-server REST interface for
    Friendbuy's referral and loyalty marketing platform. Merchants use it to
    sync customer records, generate personal referral links, track conversion
    events (purchases, sign-ups, and custom events), pull campaign analytics,
    and manage loyalty ledger balances and reward redemptions. The base URL is
    https://mapi.fbot.me/v1 (the fbot.me host is Friendbuy's Merchant API
    origin). Authentication is a two-step flow: exchange an account key and
    secret at POST /authorization for a short-lived Bearer JWT, then send that
    token as `Authorization: Bearer <token>` on every subsequent request.

    Endpoint paths in this document are grounded in Friendbuy's public
    developer documentation at developers.friendbuy.com. Request and response
    schemas are honestly modeled from the documented behavior and common
    Friendbuy payload fields; exact field-level shapes should be reconciled
    against the live reference before production use.
  version: '1.0'
  contact:
    name: Friendbuy
    url: https://friendbuy.com
  license:
    name: Proprietary
    url: https://friendbuy.com/terms
servers:
  - url: https://mapi.fbot.me/v1
    description: Friendbuy Merchant API
security:
  - bearerAuth: []
tags:
  - name: Authorization
    description: Exchange account key and secret for a Bearer token.
  - name: Customers
    description: Create and retrieve customer records and manage customer data requests.
  - name: Referrals
    description: Generate personal referral links and check referral status.
  - name: Events
    description: Track purchase, sign-up, and custom conversion events.
  - name: Analytics
    description: Pull campaign, share, click, conversion, and reward analytics.
  - name: Rewards & Loyalty
    description: Manage loyalty ledger balances, adjustments, redemptions, and coupons.
  - name: Management
    description: Block users from campaigns.
paths:
  /authorization:
    post:
      operationId: createAuthorization
      tags:
        - Authorization
      summary: Obtain a Bearer token
      description: >-
        Exchanges an account key and secret (from the Friendbuy Developer
        Center) for a short-lived Bearer JWT used to authorize all other
        Merchant API calls.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizationRequest'
      responses:
        '200':
          description: A Bearer token and its expiration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /postCustomer:
    post:
      operationId: postCustomer
      tags:
        - Customers
      summary: Create or update a customer
      description: >-
        Creates or updates a Friendbuy customer record, keyed by your
        customer id and email. Used to sync your customer base so referrals and
        loyalty can be attributed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '200':
          description: The created or updated customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /getCustomer:
    get:
      operationId: getCustomer
      tags:
        - Customers
      summary: Retrieve a customer
      description: Retrieves a customer record by customer id or email.
      parameters:
        - $ref: '#/components/parameters/CustomerId'
        - $ref: '#/components/parameters/Email'
      responses:
        '200':
          description: The requested customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /getMemberTierCustomer:
    get:
      operationId: getMemberTierCustomer
      tags:
        - Customers
      summary: Retrieve a customer's loyalty member tier
      description: Returns the loyalty program tier a customer currently belongs to.
      parameters:
        - $ref: '#/components/parameters/CustomerId'
      responses:
        '200':
          description: The customer's member tier.
          content:
            application/json:
              schema:
                type: object
                properties:
                  customerId:
                    type: string
                  tier:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /getUserData:
    get:
      operationId: getUserData
      tags:
        - Customers
      summary: Request a customer's stored data (GDPR/CCPA)
      description: >-
        Returns the personal data Friendbuy stores for a customer, in support
        of GDPR/CCPA data-access requests.
      parameters:
        - $ref: '#/components/parameters/CustomerId'
        - $ref: '#/components/parameters/Email'
      responses:
        '200':
          description: The stored user data.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /deleteUserData:
    delete:
      operationId: deleteUserData
      tags:
        - Customers
      summary: Delete a customer's stored data (GDPR/CCPA)
      description: >-
        Deletes the personal data Friendbuy stores for a customer, in support
        of GDPR/CCPA erasure requests.
      parameters:
        - $ref: '#/components/parameters/CustomerId'
        - $ref: '#/components/parameters/Email'
      responses:
        '200':
          description: Deletion confirmation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /postPersonalReferralLink:
    post:
      operationId: postPersonalReferralLink
      tags:
        - Referrals
      summary: Generate a personal referral link
      description: >-
        Generates a unique personal referral link (and code) for an advocate
        customer in a given campaign, for use in emails or your own UI.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReferralLinkRequest'
      responses:
        '200':
          description: The generated referral link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralLink'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /postPersonalReferralLinkBatch:
    post:
      operationId: postPersonalReferralLinkBatch
      tags:
        - Referrals
      summary: Generate personal referral links in batch
      description: >-
        Generates personal referral links for many advocates at once, returning
        one link per requested customer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                requests:
                  type: array
                  items:
                    $ref: '#/components/schemas/ReferralLinkRequest'
      responses:
        '200':
          description: The generated referral links.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReferralLink'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /getReferralStatus:
    get:
      operationId: getReferralStatus
      tags:
        - Referrals
      summary: Get referral status
      description: >-
        Returns the status of referrals associated with a customer or referral
        code - for example whether a referred friend has converted.
      parameters:
        - $ref: '#/components/parameters/CustomerId'
        - name: referralCode
          in: query
          required: false
          description: A referral code to look up.
          schema:
            type: string
      responses:
        '200':
          description: The referral status.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /postPurchaseEvent:
    post:
      operationId: postPurchaseEvent
      tags:
        - Events
      summary: Track a purchase event
      description: >-
        Records a purchase/order conversion so Friendbuy can attribute it to a
        referral and trigger advocate and friend rewards.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseEvent'
      responses:
        '200':
          description: The recorded purchase event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /postSignUpEvent:
    post:
      operationId: postSignUpEvent
      tags:
        - Events
      summary: Track a sign-up event
      description: >-
        Records an account sign-up conversion so Friendbuy can attribute it to
        a referral and trigger rewards for sign-up-based campaigns.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignUpEvent'
      responses:
        '200':
          description: The recorded sign-up event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /postCustomEvent:
    post:
      operationId: postCustomEvent
      tags:
        - Events
      summary: Track a custom event
      description: >-
        Records an arbitrary named custom event used to trigger custom
        campaigns or advanced attribution rules.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomEvent'
      responses:
        '200':
          description: The recorded custom event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /analytics/widget-views:
    get:
      operationId: getWidgetViews
      tags:
        - Analytics
      summary: Widget views
      description: Returns widget impression/view counts over a date range.
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          $ref: '#/components/responses/AnalyticsPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/shares:
    get:
      operationId: getShares
      tags:
        - Analytics
      summary: Shares
      description: Returns share events over a date range.
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          $ref: '#/components/responses/AnalyticsPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/clicks:
    get:
      operationId: getClicks
      tags:
        - Analytics
      summary: Clicks
      description: Returns referral-link click events over a date range.
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          $ref: '#/components/responses/AnalyticsPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/account-sign-ups:
    get:
      operationId: getAccountSignUps
      tags:
        - Analytics
      summary: Account sign-ups
      description: Returns sign-up conversions over a date range.
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          $ref: '#/components/responses/AnalyticsPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/purchases:
    get:
      operationId: getPurchasesAnalytics
      tags:
        - Analytics
      summary: Purchases
      description: Returns purchase conversions over a date range.
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          $ref: '#/components/responses/AnalyticsPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/distributed-advocate-rewards:
    get:
      operationId: getDistributedAdvocateRewards
      tags:
        - Analytics
      summary: Distributed advocate rewards
      description: Returns advocate rewards distributed over a date range.
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          $ref: '#/components/responses/AnalyticsPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/distributed-friend-incentives:
    get:
      operationId: getDistributedFriendIncentives
      tags:
        - Analytics
      summary: Distributed friend incentives
      description: Returns friend incentives distributed over a date range.
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          $ref: '#/components/responses/AnalyticsPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/rewards/referral:
    get:
      operationId: getReferralRewards
      tags:
        - Analytics
      summary: Combined referral rewards
      description: Returns combined advocate and friend referral rewards over a date range.
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          $ref: '#/components/responses/AnalyticsPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/email-captures:
    get:
      operationId: getEmailCaptures
      tags:
        - Analytics
      summary: Email captures
      description: Returns captured email addresses over a date range.
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          $ref: '#/components/responses/AnalyticsPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/email-metrics:
    get:
      operationId: getEmailMetrics
      tags:
        - Analytics
      summary: Email metrics
      description: Returns aggregate email-performance metrics over a date range.
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          $ref: '#/components/responses/AnalyticsPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/loyalty/ledger-heads:
    get:
      operationId: getLedgerHeads
      tags:
        - Rewards & Loyalty
      summary: List all customer loyalty balances
      description: Returns the current loyalty ledger balance for all customers.
      parameters:
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          $ref: '#/components/responses/AnalyticsPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /ledger-balance:
    get:
      operationId: getLedgerBalance
      tags:
        - Rewards & Loyalty
      summary: Get a customer's loyalty balance
      description: Returns the loyalty ledger balance for a single customer by customer id.
      parameters:
        - $ref: '#/components/parameters/CustomerId'
      responses:
        '200':
          description: The customer's ledger balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LedgerBalance'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /ledger-balance-custom:
    get:
      operationId: getLedgerBalanceCustom
      tags:
        - Rewards & Loyalty
      summary: Get a customer's loyalty balance by custom identifier
      description: Returns the loyalty ledger balance for a customer keyed by a custom identifier.
      parameters:
        - name: customIdentifier
          in: query
          required: true
          description: A merchant-defined custom identifier for the customer.
          schema:
            type: string
      responses:
        '200':
          description: The customer's ledger balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LedgerBalance'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /postLedgerAdjustment:
    post:
      operationId: postLedgerAdjustment
      tags:
        - Rewards & Loyalty
      summary: Adjust a customer's loyalty ledger
      description: >-
        Credits or debits a customer's loyalty point/credit balance by customer
        id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LedgerAdjustment'
      responses:
        '200':
          description: The resulting ledger balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LedgerBalance'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /postLedgerAdjustmentCustom:
    post:
      operationId: postLedgerAdjustmentCustom
      tags:
        - Rewards & Loyalty
      summary: Adjust a customer's loyalty ledger by custom identifier
      description: >-
        Credits or debits a customer's loyalty balance keyed by a custom
        identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/LedgerAdjustment'
                - type: object
                  properties:
                    customIdentifier:
                      type: string
      responses:
        '200':
          description: The resulting ledger balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LedgerBalance'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /reward/redemption-options:
    get:
      operationId: getRedemptionOptions
      tags:
        - Rewards & Loyalty
      summary: List reward redemption options
      description: Returns the available reward redemption options for the loyalty program.
      responses:
        '200':
          description: Available redemption options.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reward/redeem:
    post:
      operationId: redeemReward
      tags:
        - Rewards & Loyalty
      summary: Redeem a reward
      description: >-
        Exchanges a customer's loyalty points/credit for a reward, returning the
        issued reward or coupon.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemRequest'
      responses:
        '200':
          description: The redeemed reward.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /reward/coupons:
    get:
      operationId: getCoupons
      tags:
        - Rewards & Loyalty
      summary: List a customer's coupons
      description: Returns the coupon codes issued to a customer.
      parameters:
        - $ref: '#/components/parameters/CustomerId'
      responses:
        '200':
          description: The customer's coupons.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /postBlockUsers:
    post:
      operationId: postBlockUsers
      tags:
        - Management
      summary: Block users from campaigns
      description: >-
        Blocks one or more users (by email or customer id) from participating in
        referral or loyalty campaigns, for fraud prevention.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                users:
                  type: array
                  items:
                    type: object
                    properties:
                      customerId:
                        type: string
                      email:
                        type: string
      responses:
        '200':
          description: Block confirmation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  blocked:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer JWT obtained from POST /authorization by exchanging your account
        key and secret. Passed as `Authorization: Bearer <token>`.
  parameters:
    CustomerId:
      name: customerId
      in: query
      required: false
      description: Your identifier for the customer.
      schema:
        type: string
    Email:
      name: email
      in: query
      required: false
      description: The customer's email address.
      schema:
        type: string
    FromDate:
      name: fromDate
      in: query
      required: false
      description: Start of the date range (inclusive), ISO 8601.
      schema:
        type: string
        format: date
    ToDate:
      name: toDate
      in: query
      required: false
      description: End of the date range (inclusive), ISO 8601.
      schema:
        type: string
        format: date
    PageToken:
      name: pageToken
      in: query
      required: false
      description: Opaque token for the next page of results.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    AnalyticsPage:
      description: A page of analytics rows with an optional next-page token.
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  type: object
                  additionalProperties: true
              nextPageToken:
                type: string
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    AuthorizationRequest:
      type: object
      required:
        - key
        - secret
      properties:
        key:
          type: string
          description: Your Merchant API access key.
        secret:
          type: string
          description: Your Merchant API secret.
    AuthorizationResponse:
      type: object
      properties:
        tokenType:
          type: string
          example: Bearer
        token:
          type: string
          description: The Bearer JWT.
        expires:
          type: string
          format: date-time
    CustomerInput:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: Your identifier for the customer.
        email:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        isNewCustomer:
          type: boolean
    Customer:
      allOf:
        - $ref: '#/components/schemas/CustomerInput'
        - type: object
          properties:
            createdOn:
              type: string
              format: date-time
    ReferralLinkRequest:
      type: object
      required:
        - customerId
        - campaignId
      properties:
        customerId:
          type: string
        campaignId:
          type: string
        email:
          type: string
        firstName:
          type: string
        lastName:
          type: string
    ReferralLink:
      type: object
      properties:
        customerId:
          type: string
        campaignId:
          type: string
        link:
          type: string
          format: uri
        referralCode:
          type: string
    PurchaseEvent:
      type: object
      required:
        - id
        - amount
        - currency
      properties:
        id:
          type: string
          description: Your order/transaction id.
        amount:
          type: number
        currency:
          type: string
        customer:
          $ref: '#/components/schemas/CustomerInput'
        couponCode:
          type: string
        products:
          type: array
          items:
            type: object
            additionalProperties: true
    SignUpEvent:
      type: object
      required:
        - email
      properties:
        id:
          type: string
        email:
          type: string
        customer:
          $ref: '#/components/schemas/CustomerInput'
    CustomEvent:
      type: object
      required:
        - eventName
      properties:
        eventName:
          type: string
        customer:
          $ref: '#/components/schemas/CustomerInput'
        properties:
          type: object
          additionalProperties: true
    EventResult:
      type: object
      properties:
        received:
          type: boolean
        eventId:
          type: string
    LedgerBalance:
      type: object
      properties:
        customerId:
          type: string
        balance:
          type: number
        currency:
          type: string
    LedgerAdjustment:
      type: object
      required:
        - customerId
        - amount
      properties:
        customerId:
          type: string
        amount:
          type: number
          description: Positive to credit, negative to debit.
        reason:
          type: string
    RedeemRequest:
      type: object
      required:
        - customerId
        - redemptionOptionId
      properties:
        customerId:
          type: string
        redemptionOptionId:
          type: string