> ## Documentation Index
> Fetch the complete documentation index at: https://developers.loyaltylion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Track Share

Record that a customer shared their referral link, and on which channel. This
is what populates the share counts in your referral analytics — without it,
your dashboard shows referral visits and purchases but no shares, so call it
whenever a shopper completes a share in your storefront or app (for example,
after the native share sheet confirms, or when they copy their link).

The `channel` must be one of the channels that appear in the customer's
`referral_urls`, and should match the link they actually shared —
`device_share` for a native share sheet, `direct` for a copied link, and so
on. Shares are categorized by channel in your referral analytics.

The customer must be enrolled in the program; sharing is not available to
guests or blocked customers.

A successful request returns `204` with no body.


## OpenAPI

````yaml headless-api/2025-06/openapi.json POST /headless/2025-06/{site_id}/referrals/shares
openapi: 3.1.1
info:
  title: LoyaltyLion Headless API
  version: 2025-06
servers:
  - url: https://api.loyaltylion.com
security: []
tags:
  - name: configuration
  - name: customers
  - name: referrals
  - name: rewards
  - name: rules
paths:
  /headless/2025-06/{site_id}/referrals/shares:
    post:
      tags:
        - referrals
      operationId: referrals.trackShare
      parameters:
        - name: site_id
          in: path
          required: true
          schema:
            type: number
          description: Your LoyaltyLion Site ID
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReferralsTrackShareRequestBody'
      responses:
        '204':
          description: '204'
        '400':
          $ref: '#/components/responses/ClientErrorBadRequest'
        '401':
          description: '401'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      message:
                        type: string
                      details:
                        type: object
                        propertyNames:
                          type: string
                        additionalProperties:
                          type: string
                    required:
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '403':
          description: '403'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      message:
                        type: string
                      details:
                        type: object
                        propertyNames:
                          type: string
                        additionalProperties:
                          type: string
                    required:
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '404':
          description: '404'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - not_found
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '422':
          description: '422'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    oneOf:
                      - $ref: >-
                          #/components/schemas/TrackReferralShareErrorCustomerNotEnrolled
                      - $ref: >-
                          #/components/schemas/TrackReferralShareErrorCustomerBlocked
                    type: object
                    discriminator:
                      propertyName: code
                      mapping:
                        customer_not_enrolled:
                          $ref: >-
                            #/components/schemas/TrackReferralShareErrorCustomerNotEnrolled
                        customer_blocked:
                          $ref: >-
                            #/components/schemas/TrackReferralShareErrorCustomerBlocked
                required:
                  - error
                additionalProperties: false
        '429':
          description: '429'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - rate_limited
                    required:
                      - code
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
      security:
        - ProgramApiKey:
            - write_customers
components:
  schemas:
    ReferralsTrackShareRequestBody:
      type: object
      properties:
        customer_merchant_id:
          type: string
          minLength: 1
          description: >-
            The ID, in your platform or ecommerce store, of the customer who
            shared their referral link. For Shopify stores this can be either a
            [GID](https://shopify.dev/docs/api/usage/gids) or a regular numeric
            ID


            This must be a customer whose state is `enrolled` — only enrolled
            customers have referral links to share
          example: '100001'
        channel:
          $ref: '#/components/schemas/ReferralShareChannel'
      required:
        - customer_merchant_id
        - channel
      additionalProperties: false
    TrackReferralShareErrorCustomerNotEnrolled:
      type: object
      properties:
        code:
          type: string
          const: customer_not_enrolled
      required:
        - code
      additionalProperties: false
      title: Customer not enrolled
    TrackReferralShareErrorCustomerBlocked:
      type: object
      properties:
        code:
          type: string
          const: customer_blocked
      required:
        - code
      additionalProperties: false
      title: Customer blocked
    ReferralShareChannel:
      type: string
      enum:
        - direct
        - facebook
        - twitter
        - email
        - whatsapp
        - instagram
        - device_share
      description: >-
        Which of the customer's `referral_urls` was shared. Pass the key you
        took the link from, not the link itself — we re-derive the referral code
        from the customer and the channel, so you never have to parse one out of
        a URL
      example: whatsapp
  responses:
    ClientErrorBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  message:
                    type: string
                  details:
                    type: object
                    additionalProperties:
                      type: string
                required:
                  - message
            required:
              - error
  securitySchemes:
    ProgramApiKey:
      type: http
      scheme: bearer
      description: >-
        An API key linked to a Program in LoyaltyLion, with a set of permissions
        (scopes). API keys can be created manually, or acquired through an
        OAuth2 flow. The API key should be provided as a `Bearer` token in the
        `Authorization` header

````