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

# Add loyalty points

> Create a loyalty event that awards points to a customer

## Identify the customer

Include at least one of the following fields in the request body so Meadow can locate the customer that should receive the loyalty points:

* `customerId`
* `customerEmail`
* `customerPhone`

If the customer could not be found then the API will return a 404 response with an `error.code` of `USER_NOT_FOUND`.


## OpenAPI

````yaml POST /api/v1/loyalty-events
openapi: 3.0.1
info:
  title: Meadow Open API
  description: The API to connect to the Meadow platform
  version: 1.0.0
servers:
  - url: https://api-staging.getmeadow.com
  - url: https://api.getmeadow.com
security:
  - meadowConsumer: []
    meadowClient: []
paths:
  /api/v1/loyalty-events:
    post:
      description: Create a loyalty event that awards points to a customer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - pointsAmount
                - reason
              properties:
                customerId:
                  type: number
                  description: The customer id, as returned by customer endpoints.
                customerEmail:
                  type: string
                  description: The email address of the customer to receive the points.
                customerPhone:
                  type: string
                  description: The phone number of the customer to receive the points.
                pointsAmount:
                  type: number
                  description: The number of loyalty points to award to the customer.
                reason:
                  type: string
                  description: A note describing why the points are being awarded.
            example:
              customerEmail: customer@example.com
              pointsAmount: 55.7
              reason: New customer promotion
      responses:
        '200':
          description: Loyalty event response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoyaltyEvent'
              example:
                data:
                  organizationId: 1
                  userId: 4
                  type: open-api
                  pointsAmount: 55.7
                  reason: New customer promotion
                  updatedAt: '2025-10-13T15:53:44.336Z'
                  createdAt: '2025-10-13T15:53:44.336Z'
                  id: 1
        4XX:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
components:
  schemas:
    LoyaltyEvent:
      type: object
      properties:
        id:
          type: number
          description: The ID of the loyalty event
        type:
          type: string
          description: >-
            The source of the loyalty event, will always be `open-api` for
            events created through this API
        pointsAmount:
          type: number
          description: The number of points awarded in this event
        reason:
          type: string
          description: A description explaining why the points were awarded
        createdAt:
          type: string
          description: When the loyalty event was created
        updatedAt:
          type: string
          description: When the loyalty event was last updated
    APIError:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: A description of the error code
            code:
              type: string
              example: CODE_OF_ERROR_WILL_BE_HERE
  securitySchemes:
    meadowConsumer:
      type: apiKey
      name: X-Consumer-Key
      description: The key assigned to your company and provided via Meadow
      in: header
    meadowClient:
      type: apiKey
      name: X-Client-Key
      description: The key generated and provided by our mutual client
      in: header

````