action squareup_search_loyalty_events {
  label: "SearchLoyaltyEvents"
  description: "Searches for loyalty events.\n\nA Square loyalty program maintains a ledger of events that occur during the lifetime of a \nbuyer's loyalty account. Each change in the point balance \n(for example, points earned, points redeemed, and points expired) is \nrecorded in the ledger. Using this endpoint, you can search the ledger for events.\n\nSearch results are sorted by `created_at` in descending order."
  provider: squareup
  method: POST
  path: "/v2/loyalty/events/search"
  encoding: json
  input: {
    type: "object"
    description: "A request to search for loyalty events."
    properties: {
      cursor: {
        type: "string"
        description: "A pagination cursor returned by a previous call to this endpoint.\nProvide this to retrieve the next set of results for your original query.\nFor more information, see [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)."
      }
      limit: {
        type: "integer"
        description: "The maximum number of results to include in the response. \nThe last page might contain fewer events. \nThe default is 30 events."
      }
      query: {
        type: "object"
        description: "Represents a query used to search for loyalty events."
        properties: {
          filter: {
            type: "object"
            description: "The filtering criteria. If the request specifies multiple filters, \nthe endpoint uses a logical AND to evaluate them."
            properties: {
              date_time_filter: {
                type: "object"
                description: "Filter events by date time range."
                required: ["created_at"]
                properties: {
                  created_at: {
                    type: "object"
                    description: "Represents a generic time range. The start and end values are\nrepresented in RFC 3339 format. Time ranges are customized to be\ninclusive or exclusive based on the needs of a particular endpoint.\nRefer to the relevant endpoint-specific documentation to determine\nhow time ranges are handled."
                    properties: {
                      end_at: {
                        type: "string"
                        description: "A datetime value in RFC 3339 format indicating when the time range\nends."
                      }
                      start_at: {
                        type: "string"
                        description: "A datetime value in RFC 3339 format indicating when the time range\nstarts."
                      }
                    }
                  }
                }
              }
              location_filter: {
                type: "object"
                description: "Filter events by location."
                required: ["location_ids"]
                properties: {
                  location_ids: {
                    type: "array"
                    description: "The [location](https://developer.squareup.com/reference/square_2021-08-18/objects/Location) IDs for loyalty events to query.\nIf multiple values are specified, the endpoint uses \na logical OR to combine them."
                    items: {
                      type: "string"
                    }
                  }
                }
              }
              loyalty_account_filter: {
                type: "object"
                description: "Filter events by loyalty account."
                required: ["loyalty_account_id"]
                properties: {
                  loyalty_account_id: {
                    type: "string"
                    description: "The ID of the [loyalty account](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyAccount) associated with loyalty events."
                  }
                }
              }
              order_filter: {
                type: "object"
                description: "Filter events by the order associated with the event."
                required: ["order_id"]
                properties: {
                  order_id: {
                    type: "string"
                    description: "The ID of the [order](https://developer.squareup.com/reference/square_2021-08-18/objects/Order) associated with the event."
                  }
                }
              }
              type_filter: {
                type: "object"
                description: "Filter events by event type."
                required: ["types"]
                properties: {
                  types: {
                    type: "array"
                    description: "The loyalty event types used to filter the result.\nIf multiple values are specified, the endpoint uses a \nlogical OR to combine them."
                    items: {
                      type: "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
  output: {
    type: "object"
    description: "A response that contains loyalty events that satisfy the search \ncriteria, in order by the `created_at` date."
    properties: {
      cursor: {
        type: "string"
        description: "The pagination cursor to be used in a subsequent \nrequest. If empty, this is the final response. \nFor more information, \nsee [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)."
      }
      errors: {
        type: "array"
        description: "Any errors that occurred during the request."
        items: {
          type: "object"
          description: "Represents an error encountered during a request to the Connect API.\n\nSee [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) for more information."
          required: ["category", "code"]
          properties: {
            category: {
              type: "string"
              description: "The high-level category for the error."
            }
            code: {
              type: "string"
              description: "The specific code of the error."
            }
            detail: {
              type: "string"
              description: "A human-readable description of the error for debugging purposes."
            }
            field: {
              type: "string"
              description: "The name of the field provided in the original request (if any) that\nthe error pertains to."
            }
          }
        }
      }
      events: {
        type: "array"
        description: "The loyalty events that satisfy the search criteria."
        items: {
          type: "object"
          description: "Provides information about a loyalty event. \nFor more information, see [Loyalty events](https://developer.squareup.com/docs/loyalty-api/overview/#loyalty-events)."
          required: ["id", "type", "created_at", "loyalty_account_id", "source"]
          properties: {
            accumulate_points: {
              type: "object"
              description: "Provides metadata when the event `type` is `ACCUMULATE_POINTS`."
              properties: {
                loyalty_program_id: {
                  type: "string"
                  description: "The ID of the [loyalty program](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyProgram)."
                }
                order_id: {
                  type: "string"
                  description: "The ID of the [order](https://developer.squareup.com/reference/square_2021-08-18/objects/Order) for which the buyer accumulated the points.\nThis field is returned only if the Orders API is used to process orders."
                }
                points: {
                  type: "integer"
                  description: "The number of points accumulated by the event."
                }
              }
            }
            adjust_points: {
              type: "object"
              description: "Provides metadata when the event `type` is `ADJUST_POINTS`."
              required: ["points"]
              properties: {
                loyalty_program_id: {
                  type: "string"
                  description: "The Square-assigned ID of the [loyalty program](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyProgram)."
                }
                points: {
                  type: "integer"
                  description: "The number of points added or removed."
                }
                reason: {
                  type: "string"
                  description: "The reason for the adjustment of points."
                }
              }
            }
            create_reward: {
              type: "object"
              description: "Provides metadata when the event `type` is `CREATE_REWARD`."
              required: ["loyalty_program_id", "points"]
              properties: {
                loyalty_program_id: {
                  type: "string"
                  description: "The ID of the [loyalty program](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyProgram)."
                }
                points: {
                  type: "integer"
                  description: "The loyalty points used to create the reward."
                }
                reward_id: {
                  type: "string"
                  description: "The Square-assigned ID of the created [loyalty reward](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyReward).\nThis field is returned only if the event source is `LOYALTY_API`."
                }
              }
            }
            created_at: {
              type: "string"
              description: "The timestamp when the event was created, in RFC 3339 format."
            }
            delete_reward: {
              type: "object"
              description: "Provides metadata when the event `type` is `DELETE_REWARD`."
              required: ["loyalty_program_id", "points"]
              properties: {
                loyalty_program_id: {
                  type: "string"
                  description: "The ID of the [loyalty program](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyProgram)."
                }
                points: {
                  type: "integer"
                  description: "The number of points returned to the loyalty account."
                }
                reward_id: {
                  type: "string"
                  description: "The ID of the deleted [loyalty reward](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyReward).\nThis field is returned only if the event source is `LOYALTY_API`."
                }
              }
            }
            expire_points: {
              type: "object"
              description: "Provides metadata when the event `type` is `EXPIRE_POINTS`."
              required: ["loyalty_program_id", "points"]
              properties: {
                loyalty_program_id: {
                  type: "string"
                  description: "The Square-assigned ID of the [loyalty program](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyProgram)."
                }
                points: {
                  type: "integer"
                  description: "The number of points expired."
                }
              }
            }
            id: {
              type: "string"
              description: "The Square-assigned ID of the loyalty event."
            }
            location_id: {
              type: "string"
              description: "The ID of the [location](https://developer.squareup.com/reference/square_2021-08-18/objects/Location) where the event occurred."
            }
            loyalty_account_id: {
              type: "string"
              description: "The ID of the [loyalty account](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyAccount) in which the event occurred."
            }
            other_event: {
              type: "object"
              description: "Provides metadata when the event `type` is `OTHER`."
              required: ["loyalty_program_id", "points"]
              properties: {
                loyalty_program_id: {
                  type: "string"
                  description: "The Square-assigned ID of the [loyalty program](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyProgram)."
                }
                points: {
                  type: "integer"
                  description: "The number of points added or removed."
                }
              }
            }
            redeem_reward: {
              type: "object"
              description: "Provides metadata when the event `type` is `REDEEM_REWARD`."
              required: ["loyalty_program_id"]
              properties: {
                loyalty_program_id: {
                  type: "string"
                  description: "The ID of the [loyalty program](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyProgram)."
                }
                order_id: {
                  type: "string"
                  description: "The ID of the [order](https://developer.squareup.com/reference/square_2021-08-18/objects/Order) that redeemed the reward.\nThis field is returned only if the Orders API is used to process orders."
                }
                reward_id: {
                  type: "string"
                  description: "The ID of the redeemed [loyalty reward](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyReward).\nThis field is returned only if the event source is `LOYALTY_API`."
                }
              }
            }
            source: {
              type: "string"
              description: "Defines whether the event was generated by the Square Point of Sale."
            }
            type: {
              type: "string"
              description: "The type of the loyalty event."
            }
          }
        }
      }
    }
  }
}