Square Loyalty API

openapi: 3.0.0
info:
  version: '2.0'
  title: Square ApplePay Loyalty API
  description: 'Supercharge Square for sellers of every size. Our entire connected commerce platform  from elegant hardware to a rich suite of Square APIs  is yours to build with. Whether youre developing an app or composing a bespoke solution, this is the place to make it happen. '
  termsOfService: https://connect.squareup.com/tos
  contact:
    name: Square Developer Platform
    email: developers@squareup.com
    url: https://squareup.com/developers
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  externalDocs:
    description: 'Read the official documentation here:'
    url: https://docs.connect.squareup.com/
  x-server-configuration:
    default-environment: production
    default-server: default
    environments:
    - name: production
      servers:
      - name: default
        url: https://connect.squareup.com
    - name: sandbox
      servers:
      - name: default
        url: https://connect.squareupsandbox.com
    - name: custom
      servers:
      - name: default
        url: '{custom_url}'
    parameters:
    - name: custom_url
      description: Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`
      type: string
      example: https://connect.squareup.com
  x-square-generic-error-codes:
  - ACCESS_TOKEN_EXPIRED
  - ACCESS_TOKEN_REVOKED
  - API_VERSION_INCOMPATIBLE
  - APPLICATION_DISABLED
  - ARRAY_EMPTY
  - ARRAY_LENGTH_TOO_LONG
  - ARRAY_LENGTH_TOO_SHORT
  - BAD_CERTIFICATE
  - BAD_GATEWAY
  - BAD_REQUEST
  - CONFLICT
  - CONFLICTING_PARAMETERS
  - CURRENCY_MISMATCH
  - EXPECTED_ARRAY
  - EXPECTED_BASE64_ENCODED_BYTE_ARRAY
  - EXPECTED_BOOLEAN
  - EXPECTED_FLOAT
  - EXPECTED_INTEGER
  - EXPECTED_JSON_BODY
  - EXPECTED_MAP
  - EXPECTED_OBJECT
  - EXPECTED_STRING
  - FORBIDDEN
  - GATEWAY_TIMEOUT
  - GONE
  - IDEMPOTENCY_KEY_REUSED
  - INCORRECT_TYPE
  - INSUFFICIENT_SCOPES
  - INTERNAL_SERVER_ERROR
  - INVALID_ARRAY_VALUE
  - INVALID_CONTENT_TYPE
  - INVALID_CURSOR
  - INVALID_ENUM_VALUE
  - INVALID_FORM_VALUE
  - INVALID_SORT_ORDER
  - INVALID_SQUARE_VERSION_FORMAT
  - INVALID_TIME
  - INVALID_TIME_RANGE
  - INVALID_VALUE
  - LOCATION_MISMATCH
  - MAP_KEY_LENGTH_TOO_LONG
  - MAP_KEY_LENGTH_TOO_SHORT
  - MERCHANT_SUBSCRIPTION_NOT_FOUND
  - METHOD_NOT_ALLOWED
  - MISSING_REQUIRED_PARAMETER
  - NOT_ACCEPTABLE
  - NOT_FOUND
  - NOT_IMPLEMENTED
  - NO_FIELDS_SET
  - RATE_LIMITED
  - REQUEST_ENTITY_TOO_LARGE
  - REQUEST_TIMEOUT
  - SANDBOX_NOT_SUPPORTED
  - SERVICE_UNAVAILABLE
  - TOO_MANY_MAP_ENTRIES
  - UNAUTHORIZED
  - UNEXPECTED_VALUE
  - UNKNOWN_BODY_PARAMETER
  - UNKNOWN_QUERY_PARAMETER
  - UNPROCESSABLE_ENTITY
  - UNSUPPORTED_MEDIA_TYPE
  - V1_ACCESS_TOKEN
  - V1_APPLICATION
  - VALUE_EMPTY
  - VALUE_REGEX_MISMATCH
  - VALUE_TOO_HIGH
  - VALUE_TOO_LONG
  - VALUE_TOO_LOW
  - VALUE_TOO_SHORT
servers:
- url: https://connect.squareup.com
  variables: {}
tags:
- name: Loyalty
paths:
  /v2/loyalty/accounts:
    post:
      tags:
      - Loyalty
      summary: Square Create Loyalty Account
      operationId: CreateLoyaltyAccount
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: Creates a loyalty account. To create a loyalty account, you must provide the `program_id` and a `mapping` with the `phone_number` of the buyer.
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_WRITE
      parameters: []
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLoyaltyAccountRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLoyaltyAccountResponse'
      x-endpoint-errors:
      - error-code: INVALID_PHONE_NUMBER
  /v2/loyalty/accounts/search:
    post:
      tags:
      - Loyalty
      summary: Square Search Loyalty Accounts
      operationId: SearchLoyaltyAccounts
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Searches for loyalty accounts in a loyalty program.


        You can search for a loyalty account using the phone number or customer ID associated with the account. To return all loyalty accounts, specify an empty `query` object or omit it entirely.


        Search results are sorted by `created_at` in ascending order.'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_READ
      parameters: []
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchLoyaltyAccountsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchLoyaltyAccountsResponse'
  /v2/loyalty/accounts/{account_id}:
    get:
      tags:
      - Loyalty
      summary: Square Retrieve Loyalty Account
      operationId: RetrieveLoyaltyAccount
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: Retrieves a loyalty account.
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_READ
      parameters:
      - name: account_id
        description: The ID of the [loyalty account](entity:LoyaltyAccount) to retrieve.
        schema:
          type: string
        in: path
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveLoyaltyAccountResponse'
  /v2/loyalty/accounts/{account_id}/accumulate:
    post:
      tags:
      - Loyalty
      summary: Square Accumulate Loyalty Points
      operationId: AccumulateLoyaltyPoints
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Adds points earned from a purchase to a [loyalty account](entity:LoyaltyAccount).


        - If you are using the Orders API to manage orders, provide the `order_id`. Square reads the order

        to compute the points earned from both the base loyalty program and an associated

        [loyalty promotion](entity:LoyaltyPromotion). For purchases that qualify for multiple accrual

        rules, Square computes points based on the accrual rule that grants the most points.

        For purchases that qualify for multiple promotions, Square computes points based on the most

        recently created promotion. A purchase must first qualify for program points to be eligible for promotion points.


        - If you are not using the Orders API to manage orders, provide `points` with the number of points to add.

        You must first perform a client-side computation of the points earned from the loyalty program and

        loyalty promotion. For spend-based and visit-based programs, you can call [CalculateLoyaltyPoints](api-endpoint:Loyalty-CalculateLoyaltyPoints)

        to compute the points earned from the base loyalty program. For information about computing points earned from a loyalty promotion, see

        [Calculating promotion points](https://developer.squareup.com/docs/loyalty-api/loyalty-promotions#calculate-promotion-points).'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_WRITE
      parameters:
      - name: account_id
        description: The ID of the target [loyalty account](entity:LoyaltyAccount).
        schema:
          type: string
        in: path
        required: true
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccumulateLoyaltyPointsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccumulateLoyaltyPointsResponse'
  /v2/loyalty/accounts/{account_id}/adjust:
    post:
      tags:
      - Loyalty
      summary: Square Adjust Loyalty Points
      operationId: AdjustLoyaltyPoints
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Adds points to or subtracts points from a buyer''s account.


        Use this endpoint only when you need to manually adjust points. Otherwise, in your application flow, you call

        [AccumulateLoyaltyPoints](api-endpoint:Loyalty-AccumulateLoyaltyPoints)

        to add points when a buyer pays for the purchase.'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_WRITE
      parameters:
      - name: account_id
        description: The ID of the target [loyalty account](entity:LoyaltyAccount).
        schema:
          type: string
        in: path
        required: true
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdjustLoyaltyPointsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdjustLoyaltyPointsResponse'
  /v2/loyalty/events/search:
    post:
      tags:
      - Loyalty
      summary: Square Search Loyalty Events
      operationId: SearchLoyaltyEvents
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Searches for loyalty events.


        A Square loyalty program maintains a ledger of events that occur during the lifetime of a

        buyer''s loyalty account. Each change in the point balance

        (for example, points earned, points redeemed, and points expired) is

        recorded in the ledger. Using this endpoint, you can search the ledger for events.


        Search results are sorted by `created_at` in descending order.'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_READ
      parameters: []
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchLoyaltyEventsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchLoyaltyEventsResponse'
  /v2/loyalty/programs:
    get:
      tags:
      - Loyalty
      summary: Square List Loyalty Programs
      operationId: ListLoyaltyPrograms
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Returns a list of loyalty programs in the seller''s account.

        Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see [Loyalty Program Overview](https://developer.squareup.com/docs/loyalty/overview).



        Replaced with [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram) when used with the keyword `main`.'
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2021-05-13'
        replacedBy: RetrieveLoyaltyProgram
        guideUrl: https://developer.squareup.com/docs/loyalty-api/overview#migration-notes
      security:
      - oauth2:
        - LOYALTY_READ
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListLoyaltyProgramsResponse'
      x-endpoint-errors:
      - error-code: UNSUPPORTED_LOYALTY_REWARD_TIER
  /v2/loyalty/programs/{program_id}:
    get:
      tags:
      - Loyalty
      summary: Square Retrieve Loyalty Program
      operationId: RetrieveLoyaltyProgram
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Retrieves the loyalty program in a seller''s account, specified by the program ID or the keyword `main`.


        Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see [Loyalty Program Overview](https://developer.squareup.com/docs/loyalty/overview).'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_READ
      parameters:
      - name: program_id
        description: The ID of the loyalty program or the keyword `main`. Either value can be used to retrieve the single loyalty program that belongs to the seller.
        schema:
          type: string
        in: path
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveLoyaltyProgramResponse'
      x-endpoint-errors:
      - error-code: UNSUPPORTED_LOYALTY_REWARD_TIER
  /v2/loyalty/programs/{program_id}/calculate:
    post:
      tags:
      - Loyalty
      summary: Square Calculate Loyalty Points
      operationId: CalculateLoyaltyPoints
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Calculates the number of points a buyer can earn from a purchase. Applications might call this endpoint

        to display the points to the buyer.


        - If you are using the Orders API to manage orders, provide the `order_id` and (optional) `loyalty_account_id`.

        Square reads the order to compute the points earned from the base loyalty program and an associated

        [loyalty promotion](entity:LoyaltyPromotion).


        - If you are not using the Orders API to manage orders, provide `transaction_amount_money` with the

        purchase amount. Square uses this amount to calculate the points earned from the base loyalty program,

        but not points earned from a loyalty promotion. For spend-based and visit-based programs, the `tax_mode`

        setting of the accrual rule indicates how taxes should be treated for loyalty points accrual.

        If the purchase qualifies for program points, call

        [ListLoyaltyPromotions](api-endpoint:Loyalty-ListLoyaltyPromotions) and perform a client-side computation

        to calculate whether the purchase also qualifies for promotion points. For more information, see

        [Calculating promotion points](https://developer.squareup.com/docs/loyalty-api/loyalty-promotions#calculate-promotion-points).'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_READ
      parameters:
      - name: program_id
        description: The ID of the [loyalty program](entity:LoyaltyProgram), which defines the rules for accruing points.
        schema:
          type: string
        in: path
        required: true
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculateLoyaltyPointsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculateLoyaltyPointsResponse'
  /v2/loyalty/programs/{program_id}/promotions:
    get:
      tags:
      - Loyalty
      summary: Square List Loyalty Promotions
      operationId: ListLoyaltyPromotions
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Lists the loyalty promotions associated with a [loyalty program](entity:LoyaltyProgram).

        Results are sorted by the `created_at` date in descending order (newest to oldest).'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_READ
      parameters:
      - name: program_id
        description: 'The ID of the base [loyalty program](entity:LoyaltyProgram). To get the program ID,

          call [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram) using the `main` keyword.'
        schema:
          type: string
        in: path
        required: true
      - name: status
        description: 'The status to filter the results by. If a status is provided, only loyalty promotions

          with the specified status are returned. Otherwise, all loyalty promotions associated with

          the loyalty program are returned.'
        schema:
          $ref: '#/components/schemas/LoyaltyPromotionStatus'
        in: query
        required: false
      - name: cursor
        description: 'The cursor returned in the paged response from the previous call to this endpoint.

          Provide this cursor to retrieve the next page of results for your original request.

          For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).'
        schema:
          type: string
        in: query
        required: false
      - name: limit
        description: 'The maximum number of results to return in a single paged response.

          The minimum value is 1 and the maximum value is 30. The default value is 30.

          For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).'
        schema:
          type: integer
        in: query
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListLoyaltyPromotionsResponse'
    post:
      tags:
      - Loyalty
      summary: Square Create Loyalty Promotion
      operationId: CreateLoyaltyPromotion
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Creates a loyalty promotion for a [loyalty program](entity:LoyaltyProgram). A loyalty promotion

        enables buyers to earn points in addition to those earned from the base loyalty program.


        This endpoint sets the loyalty promotion to the `ACTIVE` or `SCHEDULED` status, depending on the

        `available_time` setting. A loyalty program can have a maximum of 10 loyalty promotions with an

        `ACTIVE` or `SCHEDULED` status.'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_WRITE
      parameters:
      - name: program_id
        description: 'The ID of the [loyalty program](entity:LoyaltyProgram) to associate with the promotion.

          To get the program ID, call [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram)

          using the `main` keyword.'
        schema:
          type: string
        in: path
        required: true
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLoyaltyPromotionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLoyaltyPromotionResponse'
  /v2/loyalty/programs/{program_id}/promotions/{promotion_id}:
    get:
      tags:
      - Loyalty
      summary: Square Retrieve Loyalty Promotion
      operationId: RetrieveLoyaltyPromotion
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: Retrieves a loyalty promotion.
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_READ
      parameters:
      - name: promotion_id
        description: The ID of the [loyalty promotion](entity:LoyaltyPromotion) to retrieve.
        schema:
          type: string
        in: path
        required: true
      - name: program_id
        description: 'The ID of the base [loyalty program](entity:LoyaltyProgram). To get the program ID,

          call [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram) using the `main` keyword.'
        schema:
          type: string
        in: path
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveLoyaltyPromotionResponse'
  /v2/loyalty/programs/{program_id}/promotions/{promotion_id}/cancel:
    post:
      tags:
      - Loyalty
      summary: Square Cancel Loyalty Promotion
      operationId: CancelLoyaltyPromotion
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Cancels a loyalty promotion. Use this endpoint to cancel an `ACTIVE` promotion earlier than the

        end date, cancel an `ACTIVE` promotion when an end date is not specified, or cancel a `SCHEDULED` promotion.

        Because updating a promotion is not supported, you can also use this endpoint to cancel a promotion before

        you create a new one.


        This endpoint sets the loyalty promotion to the `CANCELED` state'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_WRITE
      parameters:
      - name: promotion_id
        description: 'The ID of the [loyalty promotion](entity:LoyaltyPromotion) to cancel. You can cancel a

          promotion that has an `ACTIVE` or `SCHEDULED` status.'
        schema:
          type: string
        in: path
        required: true
      - name: program_id
        description: The ID of the base [loyalty program](entity:LoyaltyProgram).
        schema:
          type: string
        in: path
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelLoyaltyPromotionResponse'
  /v2/loyalty/rewards:
    post:
      tags:
      - Loyalty
      summary: Square Create Loyalty Reward
      operationId: CreateLoyaltyReward
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Creates a loyalty reward. In the process, the endpoint does following:


        - Uses the `reward_tier_id` in the request to determine the number of points

        to lock for this reward.

        - If the request includes `order_id`, it adds the reward and related discount to the order.


        After a reward is created, the points are locked and

        not available for the buyer to redeem another reward.'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_WRITE
      parameters: []
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLoyaltyRewardRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLoyaltyRewardResponse'
  /v2/loyalty/rewards/search:
    post:
      tags:
      - Loyalty
      summary: Square Search Loyalty Rewards
      operationId: SearchLoyaltyRewards
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Searches for loyalty rewards. This endpoint accepts a request with no query filters and returns results for all loyalty accounts.

        If you include a `query` object, `loyalty_account_id` is required and `status` is  optional.


        If you know a reward ID, use the

        [RetrieveLoyaltyReward](api-endpoint:Loyalty-RetrieveLoyaltyReward) endpoint.


        Search results are sorted by `updated_at` in descending order.'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_READ
      parameters: []
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchLoyaltyRewardsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchLoyaltyRewardsResponse'
  /v2/loyalty/rewards/{reward_id}:
    delete:
      tags:
      - Loyalty
      summary: Square Delete Loyalty Reward
      operationId: DeleteLoyaltyReward
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Deletes a loyalty reward by doing the following:


        - Returns the loyalty points back to the loyalty account.

        - If an order ID was specified when the reward was created

        (see [CreateLoyaltyReward](api-endpoint:Loyalty-CreateLoyaltyReward)),

        it updates the order by removing the reward and related

        discounts.


        You cannot delete a reward that has reached the terminal state (REDEEMED).'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_WRITE
      parameters:
      - name: reward_id
        description: The ID of the [loyalty reward](entity:LoyaltyReward) to delete.
        schema:
          type: string
        in: path
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteLoyaltyRewardResponse'
    get:
      tags:
      - Loyalty
      summary: Square Retrieve Loyalty Reward
      operationId: RetrieveLoyaltyReward
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: Retrieves a loyalty reward.
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_READ
      parameters:
      - name: reward_id
        description: The ID of the [loyalty reward](entity:LoyaltyReward) to retrieve.
        schema:
          type: string
        in: path
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveLoyaltyRewardResponse'
  /v2/loyalty/rewards/{reward_id}/redeem:
    post:
      tags:
      - Loyalty
      summary: Square Redeem Loyalty Reward
      operationId: RedeemLoyaltyReward
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Redeems a loyalty reward.


        The endpoint sets the reward to the `REDEEMED` terminal state.


        If you are using your own order processing system (not using the

        Orders API), you call this endpoint after the buyer paid for the

        purchase.


        After the reward reaches the terminal state, it cannot be deleted.

        In other words, points used for the reward cannot be returned

        to the account.'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - LOYALTY_WRITE
      parameters:
      - name: reward_id
        description: The ID of the [loyalty reward](entity:LoyaltyReward) to redeem.
        schema:
          type: string
        in: path
        required: true
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemLoyaltyRewardRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedeemLoyaltyRewardResponse'
components:
  schemas:
    LoyaltyEventAdjustPoints:
      type: object
      description: Provides metadata when the event `type` is `ADJUST_POINTS`.
      x-release-status: PUBLIC
      required:
      - points
      properties:
        loyalty_program_id:
          type: string
          description: The Square-assigned ID of the [loyalty program](entity:LoyaltyProgram).
          maxLength: 36
          readOnly: true
        points:
          type: integer
          description: The number of points added or removed.
        reason:
          type: string
          description: The reason for the adjustment of points.
          nullable: true
    RetrieveLoyaltyAccountResponse:
      type: object
      description: A response that includes the loyalty account.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        loyalty_account:
          $ref: '#/components/schemas/LoyaltyAccount'
          description: The loyalty account.
      example:
        loyalty_account:
          balance: 10
          created_at: '2020-05-08T21:44:32Z'
          customer_id: Q8002FAM9V1EZ0ADB2T5609X6NET1H0
          id: 79b807d2-d786-46a9-933b-918028d7a8c5
          lifetime_points: 20
          mapping:
            created_at: '2020-05-08T21:44:32Z'
            id: 66aaab3f-da99-49ed-8b19-b87f851c844f
            phone_number: '+14155551234'
          program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
          updated_at: '2020-05-08T21:44:32Z'
    LoyaltyPromotion:
      type: object
      description: 'Represents a promotion for a [loyalty program](entity:LoyaltyProgram). Loyalty promotions enable buyers

        to earn extra points on top of those earned from the base program.


        A loyalty program can have a maximum of 10 loyalty promotions with an `ACTIVE` or `SCHEDULED` status.'
      x-release-status: PUBLIC
      required:
      - name
      - incentive
      - available_time
      properties:
        id:
          type: string
          description: The Square-assigned ID of the promotion.
          minLength: 1
          maxLength: 255
          readOnly: true
        name:
          type: string
          description: The name of the promotion.
          minLength: 1
          maxLength: 70
        incentive:
          $ref: '#/components/schemas/LoyaltyPromotionIncentive'
          description: 'The points incentive for the promotion. This field defines whether promotion points

            are earned by multiplying base program points or by adding a specified number of points.'
        available_time:
          $ref: '#/components/schemas/LoyaltyPromotionAvailableTimeData'
          description: The scheduling information that defines when purchases can qualify to earn points from an `ACTIVE` promotion.
        trigger_limit:
          $ref: '#/components/schemas/LoyaltyPromotionTriggerLimit'
          description: 'The number of times a buyer can earn promotion points during a specified interval.

            If not specified, buyers can trigger the promotion an unlimited number of times.'
          nullable: true
        status:
          $ref: '#/components/schemas/LoyaltyPromotionStatus'
          description: 'The current status of the promotion.

            See [LoyaltyPromotionStatus](#type-loyaltypromotionstatus) for possible values'
          readOnly: true
        created_at:
          type: string
          description: The timestamp of 

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